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

Annotations already declare readOnlyHint/idempotent/no-destructive, so safety is covered. The description adds genuinely new behavior: it returns the full markdown body with front-matter metadata and returns a 'not found' tool error for unpublished entityType/rulesetCode pairs. That error-path disclosure is the key value beyond 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?

Purpose and usage are front-loaded, and the entity-type breakdown is dense but earns its length because it tells the agent what to author next. It is a single long paragraph, making it slightly heavy to scan, and a couple of clauses (e.g. restating rulesetCode from list_rulesets) do not add much.

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 two-param read-only lookup with an output schema already defining the return shape, the description covers purpose, routing to siblings, parameter meaning, and the failure mode (published-guide not found). Nothing an agent needs in order to call it 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by spelling out what each entityType value encompasses (stat-block math for 'monster', parent→Ability grant model for 'rule', categories membership for 'spell') and clarifying that rulesetCode must be the code, not the display label.

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+resource ('Fetch a markdown reference guide') and scopes it precisely to entity type + ruleset. It then enumerates exactly what each guide covers ('monster', 'rule', 'spell'), so an agent can distinguish it from the sibling authoring tools (vault_create_rule, vault_build_monster, etc.) without opening any schema.

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 an explicit when-to-use directive ('Call this BEFORE authoring the matching entity so the result follows the established conventions instead of inferring shape from one-off samples') and points at list_rulesets for the ruleset code. It stops short of naming alternative tools or explicit exclusions, so it is strong but not fully complete.

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