Get a foundation document

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

Annotations already declare readOnlyHint=true, and the description's 'Read the relevant foundation' is consistent. Beyond that, it adds the context that the document conveys 'the reasoning behind the system' and which design topics are covered, but it does not describe the output shape or any retieval specifics. The added behavioral content is modest, so a 3 is appropriate.

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 sentences keep it efficient, and the actionable instruction 'Read the relevant foundation before implementing in that area' is placed second. The first sentence is a long comma-separated list that overlaps the enum, but it is not bloated and still helps set scope without reading the schema.

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 single-parameter, read-only retrieval tool with a fully enumeratied schema, the description provides the essential selection context ('relevant foundation before implementing') and the resource scope. It does not describe response structure, but the document-like nature of the tool and lack of an output schema make this 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 100% and the enum fully documents all valid ids. The description's topic list largely duplicates the enum, and 'read the relevant foundation' is a usage hint rather than new param meaning. With full schema coverage, the baseline of 3 holds.

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 names the resource ('foundation') and enumerates the exact topics it covers (principles, colour, typography, etc.), so an agent can tell this is a reference-document getter. It stops short of explicitly saying 'Retrieves the foundation document for the supplied id,' and doesn't mention sibling alternatives, which keeps it at a 4 rather than 5.

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 directive 'Read the relevant foundation before implementing in that area' gives clear temporal and contextual guidance for when to use the tool. It does not mention exclusions or compare with sibling tools like get_component or get_tokens, so it lacks the explicit alternatives needed for a 5.

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