List accounts

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

Beyond readOnlyHint=true, it discloses non-obvious behavior: the pending-first/newest result ordering, the authorization requirement for hosted accounts, and the quirk that a search returns 'its best 100 in one page' rather than paginating. It does not cover rate limits or how the hourly abuse-pass flag is refreshed, but the permission and paging semantics are well surfaced.

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 admin gate is front-loaded, and the return shape and refusal behavior are grouped into separate short sentences. The opening sentence is long because it packs ordering plus every returned field, but no sentence is purely redundant.

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 compensates by spelling out the envelope ({ items, nextCursor, total }) and how to paginate. For a 6-parameter admin list tool it covers auth, filters, ordering, and returns; only error/empty-result behavior is left unstated.

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 100%, so the schema already explains every parameter, including that q is typo-tolerant word-matching and that cursor is ignored with q. The description restates the same filter set and the same search-paging caveat without adding syntax or precedence rules, so it lands at the baseline for a fully documented 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 the exact resource and scope ('accounts on this instance'), the ordering ('pending first then newest'), and every field returned, so an agent immediately knows what comes back. It does not explicitly distinguish itself from the sibling manage_users (read vs. mutate), leaving that routing to be inferred from the name and readOnlyHint.

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 gives clear operating context: admin-only, with 'Hosted non-admins are refused', and it enumerates the filter dimensions (q, status, verified, flagged) that select this tool over an unfiltered listing. It never states when to prefer a sibling such as list_deleted or manage_users, so the when-not half is absent.

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