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

Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds substantial behavioral context: constraints on authorized seats, specific failure modes (AUTH_REQUIRED, SEAT_ACCESS_DENIED), the internal-state nature of the returned JSON, and the requirement that seatId or seatName be supplied on the exact mutation call when multiple seats are authorized. This aligns with and extends the annotations without contradiction.

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 front-loaded with purpose and usage, but it is bloated with generic response-style instructions ('Never display raw JSON, data, or meta unless...', 'Prefer concise, human language...') that are not tool-specific and repeat guidance that likely belongs elsewhere. The core tool logic could be conveyed in a fraction of the length.

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?

Given the tool's low complexity and the presence of an output schema, the description covers essential aspects: purpose, output summary, constraints, failure cases, and parameter usage for writes. The main deficit is the inclusion of extraneous orchestration instructions that dilute the focus, but no critical behavioral gap remains for selecting a seat.

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 0%, so the description carries the burden. It clarifies that seatId and seatName are alternative identifiers and explains when one is required ('For a mutation when more than one seat is authorised, seatId or seatName must be supplied on that exact tool call'). This adds real semantics beyond the bare schema, though it does not delve into format or examples.

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 clearly states the tool's function: 'select an allowed LeanrIQ seat for subsequent seat-scoped operations'. This is a specific verb+resource pair and distinguishes the tool from read-only seat getters like get_current_seat or list_accessible_seats, introducing the crucial notion of selecting versus merely reading.

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 provides explicit guidance on when to use the tool: 'Select or pass a seat when you want to force a workspace, when a write is requested, or when LeanrIQ asks you to disambiguate.' It also states the constraint that only authenticated seats already granted to the user can be selected. However, it does not explicitly name alternatives or state when not to use the tool, leaving some room for ambiguity.

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