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

Annotations only declare readOnly, but the description discloses important behavior: full sections can be long, inventing a section id returns a not-found error, project_id is not guessable and must come from list_projects, and that out-of-organization ids return an obfuscated error. It also clarifies that returns prose rules, not structured data. This adds considerable transparency beyond the 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 compact yet dense, with each sentence adding a distinct behavioral or usage fact. It is front-loaded with the primary purpose and the 'Call it before' timing, then narrows down to workflow and alternatives. It carries no fluff or repetitive schema details, though the 'Read-only' is already in annotations; that duplication is minor.

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?

Given that there is no output schema, the description sufficiently explains the return behavior (index first, then section content) and error cases. It also covers prerequisites (project_id UUID, no guessing ids), constraints (limit to needed sections), and distinguishes prose rules from the data returned by sibling tools, so an AI agent can invoke the tool correctly and interpret results.

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?

Even though schema coverage is 100%, the description adds substantial semantic value: section ids must come from the index, the framework parameter should be translated to a 'framework:' section prefix, and project_id is specifically a UUID from list_projects that resolves the org and controls which sections appear. This enrichment helps an agent select and reuse parameters correctly.

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 returns the organization's development standards: coding conventions, project structure, and framework-specific rules, with a specific verb 'returns' and resource. It also distinguishes itself from siblings by name, noting that get_style_tokens should be used for visual values and get_component for component APIs.

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?

Usage guidance is explicit and comprehensive: 'Call it before any code review or review' identifies the right moment to use it; 'Call it first without section' describes the two-step index-and-select workflow; and it tells the agent to request only needed sections and explicitly flags that the framework argument is deprecated. It also names direct alternatives for different data types, showing when not to use this tool.

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