invoke_read_tool

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: the exact refusal error string 'not_a_read_tool' and the meaning of cursor for continuing truncated replies, which the agent cannot get from the annotations.

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 the core purpose and kept to a few short clauses; the cursor note is appended as a labeled aside. The parenthetical '(from find_tool)' and the stray formatting are slightly rough but nothing is wasted.

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?

No output schema exists and the description says nothing about what a successful invocation returns, and it leaves the two most important parameters (name, arguments) unexplained. It covers the routing/error behavior and pagination continuation well, but an agent still lacks enough to know how to build the invocation payload.

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 0%, so the description carries the full explanatory burden, yet it only documents 'cursor' (the next_cursor for truncated replies). The required 'name' parameter (the tool to invoke) and the 'arguments' object passed through to that tool are completely unaddressed in both description and schema.

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 states a specific action (run a read-only tool or a no-op check) and even clarifies provenance ('from find_tool'). It effectively distinguishes this from the mutating sibling invoke_tool by declaring that anything that can change state is refused, though it never names that sibling directly.

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?

It gives a clear selection condition — use this when the tool only reads or the check changes nothing — and states the failure mode ('refused with not_a_read_tool') if the condition is violated. What is missing is an explicit pointer to invoke_tool as the alternative for mutating tools, which the agent must infer.

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