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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds a useful constraint (docs are written only through docs tools, never here), but richer behavioral details like the 403 feature_disabled on releases and scope blanking live in the schema, not the description.

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 paragraphs, front-loaded with the core action and followed by scoping constraints. The opening sentence duplicates the title verbatim, which is the only real waste.

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-only file fetch with a fully documented schema and clear annotations, the description covers what is returned and the main routing caveat (docs → get_doc). No output schema exists, but a raw md file response needs little explanation, so gaps are minor.

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 100%, so the schema fully documents project_key, path, and `at`. The description's note that '`at` reads an older commit' merely restates the schema's own parameter description, adding no new syntax or format guidance. Baseline 3 applies.

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 one md file of the project tree') and the second sentence clarifies exactly what is returned (frontmatter + body + version). It partially differentiates from siblings by naming get_doc as the preferred route for docs paths, though it doesn't distinguish itself from list_dir or get_release.

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 routing guidance: docs paths 'prefer get_doc', and docs are written only via create_doc/update_doc. It also notes `at` is for older commits. It stops short of explicit when-not conditions versus list_dir or the release read tools, so it's not a full 5.

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