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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description goes well beyond by disclosing that no permission widens the result, that unprivileged callers get an empty list, that global:/connection: toolboxes are recomputed and refuse mutation, that reauthentication removes tools, and that needs_connection_count appears. It also clarifies pagination is a page, not a total, and that a non-null nextCursor means more rows.

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 description is long but densely informative and logically organized; the core purpose and scope are front-loaded, followed by permissions, id semantics, lifecycle, and pagination. Some redundancy (e.g., 'A page whose nextCursor is not null is never a total' restates prior pagination text) makes it slightly less concise, but 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 a complex list tool with no output schema, the description is remarkably complete: it specifies the return shape (result, nextCursor, prevCursor), camelCase vs REST, pagination mechanics, default page size, included toolbox types, id semantics, mutation refusal, reauthentication effects, and the needs_connection_count field. An agent has enough to call it correctly and interpret results.

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% and the schema already documents limit's default, min/max, and clamping, as well as cursor being opaque and passed from nextCursor. The description adds comparative context—limit defaults to 200 'rather than the 50 the other lists here default to'—and reinforces cursor usage in a pagination loop, which helps an agent choose values appropriately.

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 opens with a specific verb and precise scope: 'List the toolboxes the caller can see or run: their own, plus every one explicitly shared with them, with one of their teams, or with the whole organization — and nothing else.' It explicitly distinguishes itself from other list tools by stating there is no org-wide oversight listing and that it cannot answer organizational counts, and it names related tools (toolbox.get, toolbox.execute) making the resource boundary clear.

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 gives explicit when-to-use and when-not-to-use guidance: it can list a caller's visible toolboxes but 'must not be reported as if it could' answer org-wide counts. It also directs the agent to pass returned ids verbatim to toolbox.get and toolbox.execute, identifies which toolboxes are mutable via the toolbox.* lifecycle tools, and explains pagination via cursor, which is actionable.

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