get_project_docs

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

With no annotations provided, the description carries the full burden, and it delivers: it discloses that this is a read operation returning raw file content, that unpublished projects yield 404s, and that there is no path-listing capability. This gives the agent accurate expectations about side effects and failure modes.

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?

Three sentences, each earning its place: what the tool returns, how to get the index, and the key constraints and navigation behavior. The most important information is 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 simple read-only tool with two parameters and no output schema, the description covers the action, return format, failure case, and page-discovery approach. Nothing essential for invoking the tool correctly is missing.

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 input schema already documents both path and project_id. The description adds a small amount of usage context ('Omit path to get the site's index') but mostly repeats what the schema says, so the baseline of 3 is appropriate.

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 opening phrase 'Read a page of a project's published docs site' names a specific verb, resource, and scope. It also clarifies the return type (raw HTML file) and distinguishes this docs-reading tool from the many issue/module/project tools in the sibling list.

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 explicitly states when the tool works ('Only projects with docs_view enabled and a published build'), when it fails (returns a 404), and how to navigate ('follow the links in the index'). It also tells the agent how to request the site index by omitting path. No alternative docs tool exists, so no sibling routing is needed.

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