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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so 'Retrieves data without changing records' is pure repetition. The genuinely additive part is 'This endpoint does not consume credits', which matters in an API where siblings burn credits. However, 'Requires confirmed=true for this request' sits uneasily with a free, read-only call and is never explained, leaving the agent unsure whether a confirmation gate actually 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?

Front-loaded and short, but 'This endpoint does not consume credits' and 'without changing records or spending credits' say the same thing twice, and the closing confirmed=true sentence adds ambiguity rather than information. Two sentences could be cut without loss.

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?

For a read-only list tool with no output schema, an agent still lacks return-shape and pagination guidance, and the required 'confirmed' flag on a non-credit, non-mutating call is never justified. Credit-cost disclosure is a real strength, but the confirmation contradiction leaves a gap an agent must guess at.

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 50% schema description coverage, the description compensates well for the body object by mapping intent to the filters: activity type, date range, entity IDs, and free-text search. It says nothing about pagination, sort, or the legacy top-level 'types' vs 'filters.type' precedence the schema flags, and the confirmed parameter's meaning is muddled rather than clarified.

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 names a specific verb and resource ('Search activity', 'Query your past searches, enrichments, and exports') and enumerates the dimensions that can be filtered. It is clear what the tool returns conceptually, but it never names the sibling that returns a single record (dealmachine_get_activity_activity_id) or dealmachine_get_exports, so the boundary is left to inference.

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 the filter options and the free-text alternative, which implies when the tool is appropriate, but it never states when to prefer it over get_activity_activity_id, get_exports, or get_prospects_id_activity. There are no explicit exclusions or prerequisites beyond the unexplained 'confirmed=true' line.

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