Read Document

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: default plain text vs formatted mode, offset/limit paging behavior (paged reading does not apply to formatted), and the prerequisite of an open project and valid document ID. No contradictions with 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?

The description is four sentences with no redundancy. It front-loads the core action, then details options and alternatives. Every sentence adds value without unnecessary elaboration. Ideal length for a straightforward read 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?

The description covers the return type (plain or formatted text), paging, and prerequisites. Given no output schema, it adequately explains what the tool returns. Minor gaps: does not specify error handling for invalid document IDs or maximum word limits, but for a simple read tool this is acceptable.

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 75%, with three of four parameters described. The description clarifies the two format options and their implications for paging. It explains that offset/limit apply only to plain format, which the schema does not explicitly state. This adds significant meaning beyond the 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 clearly states the tool's purpose: 'Read the text of a single document.' It distinguishes from siblings by explicitly mentioning get_document_info (metadata only) and search/semantic_search (content across documents). The verb 'Read' and resource 'document' are specific and unambiguous.

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 description provides explicit when-to-use and when-not-to-use guidance: 'Use get_document_info when you only need metadata, or search/semantic_search to find content across many documents.' It also states prerequisites: 'Requires an open project and a valid document id.' This fully informs the agent about usage context.

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