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

The annotations already mark the tool as mutating, non-destructive, and open-world, and the description adds substantial behavioral detail: validation via read ping and write-scope probe, integration storage, specific error codes, token non-echoing, subscription-tier ambiguity, and beta status. No contradiction with annotations exists.

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?

The description is long but each sentence serves a purpose: purpose, validation behavior, scope requirements, success/failure contract, error taxonomy, operational caveat, security note, and beta disclaimer. It is front-loaded with the core purpose and contains no redundant filler.

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?

Given that this is an external integration call with no output schema, the description covers the essentials: token requirements, validation behavior, success/failure contract, error codes, optional scopes, security, and beta limitations. An agent has enough detail to call it correctly and handle the main failure modes.

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 only 50% because apiKey lacks a schema description, but the description compensates by explaining the token format (pat-na1…/pat-eu1…), purpose, and required scopes. The optional workspaceId is already described in the schema as defaulting to the bound workspace.

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 states a specific action ('Connect a HubSpot portal'), the exact input type (Private App access token), and what happens (validation and storage). It is clearly distinct from sibling connect tools like connect_apollo and connect_instantly by naming HubSpot and explaining the token workflow.

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?

The description gives clear usage context: use it to connect a HubSpot portal, provide a Private App token, and ensure the required scopes. It does not explicitly name alternatives or say when not to use it, but the HubSpot-specific details make the intended scenario obvious.

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