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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds context: it is a passive public catalog, it matches GET /api/help, and its content is explicitly a short flat list. This goes beyond the annotations by describing the source and return shape without contradicting them.

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 core purpose is front-loaded in the first sentence. The remaining sentences earn their place by clarifying parity with the HTTP endpoint, excluding the community /tools page, and pointing to the front_door alternative. It is slightly longer than strictly necessary, but still well organized and free of 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 zero-argument, read-only help tool with rich annotations, the description is complete: it explains what the tool returns, where the same data is rendered, what the full catalog is, and which sibling tool to use if lost. No output schema is needed given the described flat list.

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?

The tool has zero parameters and the schema fully documents that fact, so the description does not need parameter explanations. The baseline of 4 applies because there is nothing for the description to add about parameters.

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 states a specific verb and resource: 'Read the short flat list of city doors and the one tool or URL that starts at each.' It also distinguishes itself from related resources by clarifying it is the same passive catalog as GET /api/help and the front door, and by pointing to /api/tools as the full catalog.

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 description gives clear routing guidance: use help for the short flat list, /api/tools for the full catalog, and front_door when lost. It also disambiguates the human /tools page as only for third-party community tools, so an agent knows not to conflate it with this catalog.

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