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

Beyond the readOnlyHint annotation, the description explicitly states 'This tool reads and waits — it changes nothing.' It discloses nuanced behaviors such as picks being dropped on workspace/month changes, 'already_set: true' semantics, and that a 'no_selection_yet' status is a normal result rather than an error. This gives the agent a clear behavioral model beyond the structured annotations.

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 the core purpose and pairing rules, then presents detailed semantic nuances in clearly separated paragraphs. It is long and contains some parallel repetition (e.g., the workspace-dropping behavior for both counterparties and acks), but the structure makes each segment trackable and relevant, so it remains more organized than bloated.

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 complexity and the existence of an output schema, the description covers everything needed to invoke it correctly: when to call it, which kind pairs with which tool, how to interpret statuses, workspace scoping caveats, timeout behavior, and that no_selection_yet is a normal outcome requiring user follow-up. No critical operational gap remains.

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?

The input schema already covers all parameters with descriptions (100% coverage), so the baseline is 3. The description adds significant flow-level meaning, e.g., what each kind means in context, how workspace_id scopes the reported data, and how timeout_s default/clamp works. This goes beyond the schema but is somewhat redundant with schema text in places.

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 action, 'Read the user's card click', and clarifies the behavior in both states: 'returns instantly if they already clicked; otherwise waits briefly.' It also distinguishes the tool from sibling list tools by naming exactly which list tool produces which card click (well_list_workspaces, well_list_periods, well_list_missing_invoices, well_list_connectors), so an agent can tell it apart from those siblings.

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 explicitly instructs when to use the tool: 'Call it after the tool whose card asks the user to click', then maps each kind to a specific sibling tool. It also provides guidance for the 'no_selection_yet' outcome: 'end your turn by asking the user to click the card', and for workspace-sensitive cases tells the agent to pass workspace_id and compare selection.workspace_id.

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