hubspot_list_teams

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals it routes through a dispatcher under JWT/tenant/company scope, which is minor behavioral context beyond the name. However, it's silent on why destructiveHint=true and readOnlyHint=false for a list operation, and doesn't disclose any side effects, permissions required, or what 'run' means in this context. It adds token information only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is short and front-loaded with the action name, but conciseness is achieved through vagueness rather than efficient useful content. The first sentence names the action, the second describes routing, and the remaining lines are generic parameter placeholders. The structure is acceptable but the substance is thin.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, multiple annotations, and a rich set of sibling tools, the description is completely incomplete. It doesn't explain what list_teams returns, what teams exist in HubSpot, how it differs from other list tools, or why it's marked destructive. An agent would have to infer everything from the tool name alone, as the description is identical boilerplate shared across all hubspot domain-agent dispatcher actions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description adds nothing meaningful. The parameters are described as 'Free-text objective for the action' and 'Optional JSON string of structured inputs' — completely generic boilerplate that could apply to any hubspot_* dispatcher tool. No specifics about what message should contain, what the inputs JSON should look like for listing teams, or any expected format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'Run the hubspot domain agent action `list_teams`' which names the resource and an action, but it's framed as 'run an action' rather than clearly stating it lists HubSpot teams. The dispatcher jargon ('domain-agent dispatcher') obscures the actual purpose, and it doesn't distinguish itself from sibling list tools like list_crm_tasks or list_crm_contacts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It doesn't mention any of the ~100 sibling list tools, scenarios where listing teams is appropriate, or why one would pick this over list_crm_contacts. The only contextual sentence ('under your JWT, tenant, and company scope') describes routing mechanics, not usage criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.