run_three_way_match

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

With no annotations, the description carries the behavioral disclosure burden. It discloses the comparison logic, the configurable tolerances, and the flag names for missing or mismatched data (NO_GRPO, OVER_INVOICED, etc.), including that missing documents are flagged rather than causing a hard failure. It does not explicitly state that the tool is read-only or describe the result payload, but the flag list strongly implies a report-style output.

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 one dense sentence with no filler. It front-loads the core action, then gives the comparison dimensions and the flag vocabulary, so every clause earns its place and the agent can quickly parse the tool's function.

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 tool with no annotations and no output schema, the description covers the essential behavior: what is compared, under what tolerances, and what flags are emitted. The main gap is the lack of explicit read-only/non-mutating confirmation and a precise description of the return shape, but the flag list largely compensates for the missing output schema.

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 documents all three parameters at 100% coverage, which sets a baseline of 3. The description adds meaning by explaining that PO lines carry committed quantity/price, that GRPO is the receipt and AP Invoice is the invoice, and that the tolerances apply to variance detection. This helps the agent understand how poDocEntry and the tolerance parameters fit into the match logic beyond their schema descriptions.

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 uses a specific verb ('Run') and resource ('three-way match for a Purchase Order'), then specifies exactly what is compared (PO committed quantity/price vs GRPO received and AP Invoice invoiced). It lists concrete flag outputs, making the tool's function unmistakable and distinct from siblings like create_goods_receipt_po or create_ap_invoice, which create documents rather than verify them.

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 a PO needs three-way matching against its goods receipt and invoice—but it does not explicitly state a trigger condition or mention alternatives. There are no exclusions or 'use X instead' guidance, so the agent must infer the appropriate context from the tool's name and description.

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