match_three_way_list

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

Annotations already declare readOnlyHint=true, and the description adds useful behavior beyond that: ordering by newest first, the ability to pass status as a single value or list, and the meaning of from/to as a created-at window. It does not mention pagination or response shape, but the read-only safety is covered by 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?

A single sentence that front-loads the verb and resource, then efficiently packs ordering and all filter semantics. Every clause earns its place with no filler or redundancy.

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?

The description covers the main query intent and parameters, but for a list tool with no output schema it lacks guidance on pagination, result limits, or return format. Given the large sibling set and six parameters, a bit more completion would help an agent invoke it correctly.

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 0%, so the description carries the burden of explaining parameters. It maps billId, poId, status, and from/to to meaningful filters, clarifies that status accepts one value or a list, and defines from/to as a created-at window. It does not elaborate on workspaceId or date format, but the core filter semantics are present.

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 states a specific action ('List'), a precise resource ('persisted three-way matches'), and key behaviors ('newest first', filtered by billId, poId, status, and a created-at window). This clearly distinguishes it from sibling tools like match_three_way_get, match_three_way_create, and match_three_way_evaluate.

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 implies when to use the tool: when you need a filtered list of persisted three-way matches rather than a single match or a mutation. However, it does not explicitly name alternatives or state exclusions, such as using match_three_way_get for a single match or match_status_for_bill for status by bill.

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