Agent tool listing requirements

​

Listing requirements

​

Security & Privacy

• Scopes: if an agent tool accepts a HubSpot object’s property values or metadata as inputs, the corresponding .read scope must be added to your app’s required scopes configuration. For example, if a tool accepts deal data, the app must require the crm.objects.deals.read scope.
• Inputs: tools must only collect inputs and context that are necessary for their outputs. For example:
  • A “Summarize contact” tool may consider inputs like contact properties and data from associated meetings and tasks.
  • A “Create quote” tool should not require context on a contact’s meeting history.
• LLM-specific vulnerabilities: your app will be assessed for security best practices related to LLM-specific risks (e.g. indirect prompt injection or jailbreaks).
• Sensitive data: at this time, your app must not access, request, or use sensitive data scopes.

​

Compliance

• Acceptable: “Summarize contact” or “Create quote” tools
• Unacceptable: “Social scoring,” “Employment decision,” or “Parental leave predictor” tools

​

Reliability & Performance

• Tool type: toolType should match the descriptions in the agent tool reference documentation:
  • GET_DATA: retrieves information from HubSpot or external sources.
  • GENERATE: generates content, summaries, analyses, or suggestions based on the provided inputs.
  • TAKE_ACTION: performs CRM actions, such as creating notes or assigning tasks to owners.
• LLM description: llmConfig.actionDescription should follow the description best practices.
• Outputs: your tools must return the outputs specified in their configurations. For example, if your tool’s outputFields array includes a success_message of "type": "string", the tool should return that property in the expected format with every run.
• Performance matches descriptions: your tools must perform operations successfully and as described in its actionDescription, llmConfig.actionDescription, and input and output descriptions.
• Testing video: you must provide a short video demoing successful agent runs using your tools (see the Submitting your tools for approval section below).
• HubSpot testing: your tools must pass any user acceptance tests the HubSpot Ecosystem Quality team performs.

​

Usability

• Natural language: all tool names, labels, descriptions, inputs, and outputs must use natural language and be clear and intuitive.
• Your tools must perform a clearly defined operation and be consistent with the specified outputs.
• Organization names: tool names may cite the external platform they interact with. However, they should not include an attribution to your organization in the tool name. Instead, you may use the tool description. Labeling and association will be handled by the HubSpot UI. For example:
  • Acceptable: “Send Slack notification” or “Create Acme quote”
  • Unacceptable: “Send Slack notification by Alpha Co.” or “Create Acme quote by Omega Inc”
• Tool names should:
  • Begin with a verb (e.g. “Create…”)
  • Start with a capital letter
  • Be between 3-7 words
• Tool names should not include:
  • Capitalized words except for the first word, proper nouns, and acronyms
  • Underscores or camel case
  • Jargon or hyperbole
  • Generic terminology (e.g. “Process data”)
  • Specific agent names or use cases
• Tool descriptions should:
  • Be between 50-150 characters
  • Provide more detail than the name
  • Be written in present tense
  • Be clear about whether the tool generates a generic output or something specific in HubSpot (e.g., “This tool generates text for a landing page” or “This tool creates a HubSpot landing page draft”)
• Inputs: every tool input should have a label and description. Each description should:
  • Relate to the input’s label
  • Match the input’s type
  • Explain what to provide
  • Be concise and accurately reflect the input’s purpose

​

Value

• Acceptable: “Create Xero invoice” and “Send Omega gift” tools
• Unacceptable: a “New hire HubSpot setup” tool

​

Submitting your tools for approval

• Production app ID: identify the app ID you intend to update or list on the HubSpot Marketplace.
• App ID and build for review:
  • Recommended: identify your production app ID and the latest successful build with agent tools.
    • If your app is already listed on the HubSpot Marketplace, this build will have failed to deploy.
  • Alternative: identify your staging app ID and latest deployed build.
• Tool UIDs for review: list the uid values for all agent tools.
• Testing video: record a short video describing the user acceptance tests you completed with this tool build. The demo video must meet the following requirements:
  • Be at least three minutes long
  • Include audio (preferred) or text descriptions
  • Include descriptions of the tool(s) and common use cases
  • Show the test runs you completed
  • Recommended: if submitting your production app ID for review, this must be recorded while developing locally.