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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description goes further by disclosing return shapes for each mode (short index with slug/title/whenToUse/kind vs. a full markdown guide) and a key constraint that guides never hold prices, which is essential behavioral context.

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-loads purpose and the when-to-call condition, then efficiently covers each mode and the price caveat. Every sentence adds distinct operational value, with no 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?

For a two-parameter, read-only discovery tool with no output schema, the description provides complete guidance: when to use it, how each mode behaves, what content to expect, and how it relates to the pricing sibling tool. Nothing material 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 0%, so the description must carry all parameter meaning. It fully explains the no-argument default, the query parameter with plain-language examples, and the slug parameter with the format of the returned guide — more than sufficient to compensate for the schema gap.

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?

States a specific resource (free how-to guides) and when to use it (when unsure how to do a task), directly distinguishing its role from siblings like search_catalog for live pricing. An agent immediately knows this is the guide retrieval tool.

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?

Explicitly says 'Call it when unsure how to do a task' and then describes all three invocation modes (no args, query, slug). It also routes the agent to search_catalog for live prices before a paid call, giving a clear alternative for price information.

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