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

Annotations already declare readOnlyHint/idempotentHint/non-destructive/closed-world, so the safety profile is covered structurally. The description adds genuine behavioral context beyond that: this is a precondition step in a build sequence, and its output includes a rubric and design_warnings that must be resolved. It stops short of saying anything about the size or format of the returned guide.

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?

Front-loaded with the tool's identity before the workflow and parameter notes, and every sentence carries actionable content. The topic enumeration in the first sentence is long and run-on, but it maps to the guide's actual scope rather than being filler.

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?

With no output schema, the description carries the burden and mostly does: it says what the guide covers, when to call it, how to parameterize it, and how to act on the result. Only the concrete shape of the returned document (sections, ordering) is left unstated, which is minor for a reference-retrieval tool.

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 baseline is 3, but the description goes further by defining each trait enum in the agent's terms — printable (downloadable PDF that keeps the look), live (self-updating numbers), kiosk (an office screen) — which the enum list alone does not convey. workspace_id semantics live only in the schema, keeping this from a 5.

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?

Names a specific verb and resource (get the design guide) and unpacks exactly what the artifact contains — brief questions, build-and-review procedure, rules for rhythm/type/charts/accessibility/locale, and the scoring rubric. It is clearly distinguishable from siblings like get_page_recipe (document recipes) and get_brand_kit, which it routes to instead of duplicating.

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?

Gives an explicit timing rule ('Call it BEFORE building any of the three'), states which inputs to supply, and then names the downstream siblings and actions (list_page_recipes, publish with document_kind/printable, fix design_warnings). An agent knows when to call this and what to do after, without inference.

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