fetch

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully established. The description adds value by disclosing the pagination behavior via metadata.next_offset and the notion that long documents require multiple calls; this is useful context beyond the annotations, but no error behavior, auth requirements, or termination conditions are disclosed.

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?

Two short sentences with the action front-loaded and the pagination guidance placed second. There is no filler or restating of schema details; each sentence earns its place, though the second sentence could be slightly more explicit about parameter semantics.

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 tool is a simple read with rich annotations and only three parameters, and the description covers the key pagination loop needed for long documents. Still, without an output schema, the response shape beyond metadata.next_offset is left to inference, and id semantics remain unexplained, so an agent may still have questions before calling confidently.

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% and parameter titles ('Id', 'Length', 'Offset') carry no explanatory weight. The description hints at offset/length usage through the next_offset instruction, but it never clarifies what id refers to (search result handle vs document ID) or what units length uses, so the agent must infer critical parameter meaning.

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 'Fetch a search result by ID' names a specific verb and resource, making the core action clear. The need to distinguish from siblings is moderate: among siblings like search and read_file, the search-result framing positions it as the complement to search, but it does not explicitly name any sibling to avoid confusion.

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 pagination instruction ('Follow metadata.next_offset to read a long document completely') conveys clear context for when to use repeated fetches, implying this tool is for retrieving search results incrementally. However, there is no explicit statement of when not to use it or which alternative to prefer (e.g., read_file vs fetch), leaving some routing to inference.

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