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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: the call returns a run ID immediately (async execution) and defines the retry protocol ('if dispatch is retry_required, repeat the same request with the same client_request_id; do not create a new run'). It does not mention polling via research_status or how to cancel via cancel_research.

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?

Four short sentences, front-loaded with what the tool does and followed by prerequisites and retry rules; each sentence carries actionable content. Slightly dense but free of 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?

For a six-parameter async tool with a nested limits object and an output schema (the run ID), the description covers invocation prerequisites, the immediate return, and retry semantics. It omits any pointer to the companion research_status/cancel_research tools for following up on the returned run, which is the one notable 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 67%, with descriptions already present for team_id, person_id, categories, and client_request_id. The description reinforces the retry meaning of client_request_id and the self-vs-Team split, which the schema only gestures at. However, the nested 'limits' object and 'categories' are left entirely to the schema, so it adds only partial value over structured fields.

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 concrete verb and resource: 'Research and save cited person knowledge with noticed's bounded research swarm.' It also signals the async dispatch model ('returns a durable run ID immediately'), which distinguishes it from the synchronous-looking siblings. It does not name adjacent tools like enrich_person or submit_enrichment_research, so the boundary with those 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?

Gives explicit preconditions: self research works before connecting external profiles, while research on another person requires a selected Team. That is clear context an agent can act on. It stops short of naming alternatives or exclusions (e.g., when to prefer enrich_person or submit_enrichment_research), so it is not a full routing statement.

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