Read a site

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so no restatement is needed. The description adds valuable behavior: the plain-text vs original-text difference depending on the file parameter, inclusion of versionId and truncation information, and a policy caveat ('Respects the artifact's text/AI access policy'). That goes beyond the structured 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?

Four sentences, each earning its place: purpose, slug lookup, file-vs-plain-text return behavior, and routing/alternatives. There is no filler, redundancy, or irrelevant detail; the key facts are front-loaded.

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?

For a read tool with six parameters and no output schema, it covers the essential behavioral context: what is read, what is returned in each mode, truncation reporting, and access policy. The schema covers remaining parameter details, so only minor extras like pagination or max_chars interplay are absent.

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 coverage is 100%, so the schema already documents all six parameters. The description adds marginal clarification about the file parameter's effect on return type and indirectly references version_id, but it does not substantially deepen understanding of the other parameters.

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 opens with a specific verb and resource ('Read an existing remote report, page or document') and states the intended use cases (summarize, answer questions, reuse earlier work). It explicitly separates itself from get_site, edit, and export, so an agent can identify it without opening the schema.

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 clear when-to-use guidance ('Read an existing remote report...') and direct routing for alternatives: 'Use get_site for filenames, edit to change one file, and export for binary files or a complete backup.' It also tells the agent to 'Find its slug with find if needed,' covering the prerequisite step.

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