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

Annotations already declare readOnly=false, destructive=true, idempotent=true, openWorld=true, so the safety profile is largely supplied. The description adds real behavioral context — fresh context, no tools available to the model, revision-pinned sources, and that outputs are proposals rather than saved changes — but the claim 'never saved project changes' sits in tension with destructiveHint=true and is not reconciled, leaving the agent unsure whether this call can mutate state.

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 the core action and scope before the mode mapping and the proposal caveat. Minor waste in the abstract closing line ('The host applies the creator's measured routing preference'), which is jargon-heavy and low-information for an agent deciding how to call the tool.

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?

An output schema exists, so return values need not be explained, and the mode semantics are covered. But for a 6-parameter, nested-object tool with 5 required fields, the description says nothing about what work_id identifies or what request_key is for, which are exactly the fields an agent is most likely to get wrong.

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 only 50% schema description coverage, the description compensates partially: it clarifies that sources must be complete and revision-pinned (explaining the required resource_id/revision pair) and that task must be one of the three named modes. However, work_id and request_key get no meaning from the description, and the idempotency role of request_key is left to inference despite idempotentHint=true.

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 concrete verb plus resource — 'run one bounded extraction, draft or semantic selection on complete, revision-pinned source resources' — and enumerates the three task modes that match the task enum. It implicitly separates itself from generic execution siblings (run_workflow, call_studio_tool) by stating the task runs 'with fresh context and no tools', but it never names an alternative explicitly.

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?

'Use extract_facts for supported facts, draft_text for one constrained piece of writing, select_context for relevance scores' is explicit mode-selection guidance tied to the enum values. What is missing is the inverse: when to reach for a different toolset (e.g. call_studio_tool, run_workflow) instead of a bounded single-pass model task.

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