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

The annotations only declare readOnlyHint=true, so the description has to add the behavioral detail, and it does: the result includes cancelled history, and taking a need off the shelf does not change its status (status and displaying are orthogonal). The login requirement is also stated. It does not describe the ordering or the shape of the returned records, which is a minor gap for a read-only list tool.

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 compact and front-loads the login and listing scope ahead of the routing hints. The telegraphic, semicolon-separated style keeps every clause informative, but the sparse phrasing makes it more of a shorthand cheat sheet than a structured description.

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 read-only, five-parameter list tool with full schema coverage and no output schema, the description covers the auth requirement, the result scope, the status-vs-visibility trap, and routing to the correct sibling for every adjacent action. Nothing essential to invoking it correctly is missing.

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, but the description adds cross-parameter interpretation rules beyond the schema: do not infer on-shelf visibility from status=OPEN, and pass displaying=true only for on-shelf items. That clears up a real source of misuse even though the field-level definitions are already in 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 sentence says explicitly that this lists the caller's own needs, including cancelled history, which is a concrete verb plus resource and scope. It does not identify itself against list_needs_feed or find_customer_needs, which are the nearest siblings, though it does name the neighboring tools for the related follow-up actions.

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 concrete routing conditions: use get_conversation_needs when the claim-completion state does not reflect the need's overall status, and use get_need_recommendations for recommendations. It adds the operational rule 'only pass displaying=true when the need is still on the shelf.' It lacks a clear statement of the boundary relative to list_needs_feed or search_needs for browsing other people's needs.

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