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

With no annotations, the description carries the full burden and does well: it discloses the security property (secret never revealed), the privilege tiers required for each op, the group-scope lifecycle caveat ("while it is their active one"), and a concrete failure mode with its error code (`grant_quota_required`) plus the metering units per provider. It omits what revoke actually does (immediate cut-off? cascading?) and whether grant is idempotent.

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-loaded with the core security claim, then organized op-by-op with slash and pipe separators so each clause maps to a parameter or a branch. It is dense to the point of near-cryptic nesting (parentheses inside parentheses around the quota units), which costs some scannability, but almost no sentence is 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 an 8-parameter, no-annotation, no-output-schema tool with multiple branches, the description covers authorization, scope selection, quota semantics, units, and an error code — enough to call it correctly. The gaps are `_org`, the shape of a successful grant response, and revoke side effects.

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 compensate, and it does for most parameters: `provider` doubles as the list filter and the grant/revoke key, `target` accepts email or sub, `group_id`/`org_id` are tied to their scopes, and `daily_quota` gets units and a hard > 0 requirement for elevenlabs and higgsfield. The `_org` parameter is never mentioned anywhere, leaving one of eight parameters undocumented.

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?

"Platform keys as a RIGHT — never reveals the secret" plus the op enumeration (list / grant / revoke) and the explicit routing of raw-secret posing to the dashboard gives a specific verb+resource identity. An agent can tell this is the oto platform-key entitlement manager rather than the many other oto_admin_* tools. It stops short of naming the siblings it must not be confused with.

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 states the conditions per op (list requires platform admin and supports an optional `provider` filter; grant/revoke require super admin) and enumerates the three scope modes with their required identifiers. It also names an explicit alternative — the dashboard — for posing a raw key/secret. It does not say when to prefer revoke over re-granting, or what to do if a grant already exists.

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