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

The annotations already declare readOnlyHint, destructiveHint:false and openWorldHint:false, so the description adds several genuinely useful details: the page cap ("at most 20 tools at a time"), and the contents of the single-tool view, including whether that tool "runs at once, asks the person first, or is off" and "any values the project adds to a call." Those approval and injection semantics go beyond what the annotations and the schema convey.

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?

The purpose is stated up front, but the core is a single 60-plus-word run-on sentence that repeats "outside agent" three times and nests three modes in one clause. It is parseable but not efficient; the detail-view contents could be a separate, shorter sentence.

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?

The definition has an output schema, so return shapes need no prose, and annotations already cover the safety profile. What is left, namely the three access modes, the 20-item pagination limit and the detail-view contents, is covered; the only gap is brief guidance on when to choose this over the related sibling tools.

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?

Because schema description coverage is 100%, it is reasonable to treat the schema as the baseline (3), and the description still adds something on top of it: the $find and $tool parameters are framed as alternate modes ("finds them by words" vs "gives one tool in full"), and the 20-item page cap clarifies how $offset behaves. The remaining parameters (agent, project) are explained only by the schema, not by the prose.

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 gives a specific verb with a resource ("lists the tools of an outside agent"), and it explains what "outside agent" means with a concrete example ("an agent that runs at its own service, such as an ads tool"). It covers three modes (list, search, fetch one tool in full), but the opening phrasing — "What an outside agent on the project can do: lists the tools..." — names no sibling such as use_agent or confirm_agent_call, so the tool's boundaries remain unclear.

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 three modes are merely implied by the parameter names ($find, $tool) and folding both searching vs. fetching-one into a single sentence, and the description never says when to prefer this tool over its related siblings (use_agent, confirm_agent_call, open_project). It is enough to call the tool, but it leaves the agent to infer which mode it should use.

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