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

Annotations already declare read-only/non-destructive/open-world, and the description adds real behavioral context on top: results are newest-first, 'empty result means none recorded yet, not that none happened' (crawl-dependent latency caveat), and no PII is exposed. The empty-result caveat is exactly the kind of non-obvious behavior that prevents misreads.

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?

Dense and front-loaded: the trigger condition leads, followed by the parameter routing and the operational caveats. Every sentence carries information, though the multi-clause opening and trailing caveats make it slightly heavier than ideal.

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 9-parameter, all-optional tool with no output schema and 89% schema coverage, the description covers trigger, routing, pagination ordering, and the empty-result interpretation. It does not discuss how to paginate with limit/offset or what a signal record contains, but these are largely covered by the schema or non-essential for correct invocation.

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 description coverage is 89%, so the baseline is 3 and the schema already documents most parameters well. The description adds intent-level semantic value by mapping the user's question to the moved_from/moved_to parameters, which is more than the schema alone conveys about how to drive the tool.

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 specific verb and resource — 'which companies recently started, stopped or switched using a technology' — with concrete examples (left Intercom, adopted HubSpot) and expands scope to growth and hiring changes. This is clearly distinct from siblings like get_technologies (current stack) and lookup_company (single-company lookup).

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 triggers on a user question pattern and tells the agent how to route it ('set moved_from or moved_to'), plus notes the broader growth/hiring coverage. The 'no API key needed; no contact reveals' note also tells the agent when this is the viable choice for contact-free queries.

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