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

No annotations are provided, so the description carries the full burden — and it uses it well. It discloses the response carries a `next` affordance: "the sub-resources that exist for this entity and the exact tool call that retrieves each, computed from this record," and the include_next=false toggle to omit it. This meaningfully exceeds the schema, which only says include_next 'omits the next affordance block.' Minor gaps remain (no mention of empty-tag behavior or error conditions), but the key navigation trait is fully explained.

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?

Four short sentences, purpose front-loaded, zero filler. Each sentence earns its place: purpose, routing to alternatives, the `next` behavior, and the include_next toggle. The structure mirrors how an agent consumes it — first decide if this is the tool, then understand its pagination affordance.

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 mutli-part entity fetch (metadata + neighbors + provider/API samples + next navigation) with no output schema, the description covers the essentials: what comes back, how to get the full list, and how its navigation block works. The only notable gap is that it doesn't state how many 'neighbor tags' appear or describe the response format/shape explicitly — but the explicit `next` routing substantially compensates for the absence of an output schema.

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 80%, so the baseline is 3. The schema already documents view, limit, context, and include_next thoroughly. The description adds modest value: 'top sample... (with totals)' contextualizes limit, and 'results carry `next`... computed from this record' explains what include_next actually toggles. This is helpful but marginal on top of an already-rich schema — it doesn't move above baseline.

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+resource and precise content: "One tag: its metadata, neighbor tags, and a top sample of its providers and APIs (with totals)." It distinguishes itself from siblings by naming the alternative plumbing — find_apis?tags=slug and find_providers?tags=slug — so an agent can differentiate this from find_tags, get_tag_group, or the full-list tools 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?

Explicit when-to-use vs alternatives: "Use find_apis?tags=slug / find_providers?tags=slug for the full ranked list, or view=full here." This tells the agent exactly when to switch tools versus when to stay in get_tag with view=full. The schema's view parameter reinforces this, noting when get_api/get_provider is the right call. Nothing is left to inference.

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