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

Annotations only declare readOnlyHint=true, so the description carries the rest and does it well: it discloses that the result is not paginated (next_cursor always null), that sorting is busiest-first, that a MARKET-tier key receives churn components while a lower-tier key does not, and the crucial anti-double-counting rule for Provider vs Vendor rows. Auth/tier behavior is covered at a high level; a note on what happens with an unauthenticated or wrong-tier key beyond 'does not receive' is the main omission.

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?

Structure is decent (what the directory returns, then how kind selects row types), but much of the kind/country prose restates the enum and parameter descriptions almost verbatim from the schema, notably the 403-for-lower-tier-key rule and the country field inventory. The double-counting warning earns its place; the duplicated parameter detail does not.

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, the description fully carries the return contract: field inventory per item, the extra country-scoped fields, tier-gated churn components at 7d/30d/90d, sort order, and pagination behavior. An agent can interpret the response without guessing, and the Provider/Vendor aggregation caveat removes the most likely analytical error.

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 and the schema already documents kind and country mechanics. The description adds intent and consequence beyond the schema: country is for 'compare providers within one market instead of network-wide', and the warning that Vendor participants are always also counted in their serving Provider, so rows must never be summed into one total, share or rank. That is real semantic value on top of 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 gives a specific verb and a precisely scoped resource: 'The Access Point directory: every Provider in its serving role, with its member seats and roster size (current participant count), busiest first.' An agent knows exactly what rows come back and in what order. It never explicitly distinguishes itself from the singular get_access_point or from list_providers, so it stops short of a 5.

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?

Usage guidance exists at the parameter level ('Pass ?country=CC to compare providers within one market instead of network-wide', and the kind selection rules), which is genuinely helpful for steering an invocation. However, it never states when to reach for this tool versus the sibling directory tools, so tool-level selection 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.