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

With no annotations, the description carries the full burden and does so well: it discloses cost (15 credits), latency (60-180s), the ~200s wait limit and job_id fallback, and the concrete side effects of persist=true — company_description is replaced, team/contacts/social/pricing records are created, and blank contact channels are filled. That is exactly the mutation risk an agent needs before calling.

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 with purpose, then cost/time, then persistence semantics, then the escape hatch — a logical order with almost no filler. The single long middle sentence about persist is dense and could be split, but nothing is redundant.

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?

Covers the async/job pattern, cost, latency, and mutation effects, which are the hard parts for a 5-param tool with a nested auto_update object and no output schema. The auto_update scheduling object is never addressed, and there is no statement about what the response contains when it completes in-band, leaving a small 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?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the consequence of persist=true (what gets saved, what gets overwritten) rather than just its default. It does not mention auto_update, company_name, or company_website, so it is not complete.

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+resource (deep-scan the agent's company website + LinkedIn) and enumerates exactly what it extracts. It is clearly distinguishable from scan_website_quick, scan_agent_website and preview_deep_scan, which it explicitly contrasts by naming the preview as a prerequisite.

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?

Gives an explicit gating rule ("Only call after preview_deep_scan and the user's approval") plus a follow-up route: if the call times out with a job_id, use get_agent_job. Both the when-to-use and the after-use path are named with sibling tool names.

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