Sync to HubSpot

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

Annotations cover safety (readOnly=false, destructive=false, idempotent=true, openWorld=true), yet the description adds substantial extra context: idempotency by email, the confirm/token gate, overwrite_existing default of fill-empty-only, suppressed exclusions, OPENSDR_READ_ONLY honoring, and demo-mode simulated:true. This is richer than the annotations alone.

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?

Front-loads the core action, then layers the two-phase protocol, idempotency, defaults, and mode notes. Every sentence conveys actionable information with no filler, despite the tool's complexity.

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?

No output schema exists, so return values are handled by the demo-mode note. For a mutation tool with 8 params the workflow, defaults, and environment flags are well covered, but the semantics of list and prospect_ids remain unstated, a minor completeness gap.

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?

With 0% schema description coverage, the description does heavy lifting: it explains confirm, confirmation_token, overwrite_existing, include_suppressed, lifecycle_stage, and the note behavior. However, the list and prospect_ids parameters are never explained, leaving part of an 8-param schema undocumented.

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?

States a precise verb+resource+keying scheme: 'Upsert prospects into HubSpot as contacts (keyed by email), with an optional lifecycle stage and a note.' This clearly separates it from siblings like sdr_push_to_campaign and sdr_save_prospects without needing their schemas.

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?

Explicitly prescribes the when/how flow: call without confirm to preview, show the preview, then call again with confirm=true plus the confirmation_token after approval, and re-preview if any approved contact changes. It also states default behavior for overwrite_existing and suppression inclusion, so the agent knows which choices to surface.

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