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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: counts only with no agent identities, demand counts suppressed until a category has enough weekly requests, owner_key gated detail, no charge, and a guarantee that it never affects ranking or routing. The data-suppression threshold and the 'results differ without owner_key' split are exactly the kind of context annotations cannot convey.

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?

It is front-loaded with the use condition and contains no filler, but the opening sentence is a single ~90-word clause stack enumerating every returned metric, which is harder to scan than a short bulleted list would be. Everything present earns its place; the packaging could be tighter.

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 and three parameters, the description carries the return-value burden itself and does so by enumerating each metric group, plus stating the gating rule for private vs public data. Nothing an agent needs to decide whether to call it, and what to expect back, 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; the description goes beyond it by explaining the consequence of each parameter path — owner_key (and the requirement to use the newest key, since each verification issues a new one) unlocks private diagnostics, while omitting it yields public numbers plus verification instructions. The days window and server-address formats are left entirely to the schema.

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 names a concrete report: category-level agent demand counts (7/30 days), this server's impressions and picks, and verified-owner metrics (agent words, competing picks, failure reasons, uptime, tool changes, token cost, handshake time). That is specific enough that an agent can tell it apart from adjacent tools like my_7maps_usage or claim_mcp_server without opening the 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 states the triggering condition plainly ('when the person you work for owns an MCP server on the 7Maps map and wants to know how AI agents look for servers like it') and routes the ownership case to claim_mcp_server when owner_key is absent. It does not name a when-not case or an explicit alternative for non-owner or own-usage questions, so it stops just short of full routing guidance.

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