nidhipati — proof of spend for AI agents

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes beyond them by disclosing a non-obvious return behavior: three separate amounts rather than one sum, plus the rationale that summing them would overstate recoverable money. What remains undisclosed is whether findings are per-record or aggregated, and whether 'records' is validated or silently skipped when malformed.

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?

Front-loaded with the action verb and the anomaly list, then a second sentence that explains the unusual three-amount return shape and its rationale. Dense but every clause earns its place; the anomaly enumeration is long but directly useful for matching against a caller's intent.

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?

With no output schema, the description appropriately explains the return structure (three separate amounts) and warns against misinterpreting it. Combined with a fully documented input schema and read-only annotations, the definition is sufficient to select and invoke the tool; only the granularity of per-finding results is left to guesswork.

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 100% and the schema documents both 'records' (row fields incl. ts, agent_id, tool, quote, settled, status) and 'policy' (limit_usd). The description adds no syntax or format guidance for either parameter; 'budget breaches' only obliquely signals that the policy parameter drives that check. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Find') against a precisely scoped resource (settled agent calls) and enumerates the anomaly classes it detects: duplicates, price escalation, failed-but-billed calls, runaway loops, missing refunds, model overpay, unknown asset/network, budget breaches. An agent can tell this is an anomaly-detection pass over a supplied list rather than a reconciliation, verification, or report-resolution step.

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 one explicit when-not ('Do NOT use as a statement of money actually returned'), but that is an interpretive warning about the output, not a routing rule between tools. No sibling (reconcile_books, verify_receipt, resolve_report, reserve_report) is named, and no precondition such as 'call after settlement' is stated.

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

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

Goes well beyond the read-only/non-destructive annotations: it discloses the matching priority order, the invoice-window constraint, the exact return semantics ('names what is left over in both directions: invoices nobody paid, money nobody invoiced, invoices paid twice'), and dedup behavior ('a duplicate is counted once, never twice'). It also flags a key limitation about payer identity.

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?

Four short sentences, front-loaded with the matching rule, followed by output semantics and a caveat. No redundant restatement of the title or schema, and every sentence carries information.

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?

With no output schema, the description takes on the burden of describing results and does so precisely by enumerating the three leftover categories and the dedup rule. Combined with the caveat about payer attribution, an agent has everything needed to call and interpret it.

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 meaning the schema does not: it explains that memo is the primary join key and that amount plus asset are compared inside the invoice creation window. This tells the agent how the two arrays are actually consumed together.

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?

States a specific verb and resource ('Match invoices to stablecoin transfers') plus the exact matching algorithm (memo first, then amount/asset within the invoice window). Nothing in the sibling set (reserve_report, resolve_report, verify_receipt, audit_spend) overlaps with this reconciliation job, so the purpose is unambiguous.

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?

Provides an explicit exclusion: 'Do NOT use as proof of who the payer was,' which steers the agent away from an attribution misuse. It does not name alternative tools for attribution or explain prerequisites, so it falls short of a full when/when-not routing guide.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description still adds real behavior: verdict categories (backed/underbacked/incomplete), the null-ratio refusal rule when a line is unpriced, and a per-line sha256 evidence hash. The only gap is that it does not describe the shape of the returned report.

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?

Three tight sentences, each earning its place: transformation, decision rule with rationale, then an explicit misuse warning. Front-loaded with the core action.

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?

No output schema exists, and the description enumerates the possible verdicts and the null-ratio condition, which is what an agent most needs. The remaining gap is the internal structure of the nested reserve document, which neither schema nor description specifies.

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?

With one required parameter at 100% schema coverage, the baseline is 3. The schema description is thin ('Reserve document.') and the nested object structure is undocumented; the description only hints that the document contains lines with prices. It adds marginal but not compensating detail.

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?

States a specific verb and resource: turning an issuer's reserve lines into a NAV with formulas and a sha256 evidence hash per line. The output artifact (verdict plus backed ratio) is clearly distinct. It does not name any sibling tool, so an agent gets no explicit differentiation from resolve_report or reconcile_books.

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 'Do NOT treat the result as a statutory audit' line gives a clear interpretation boundary, and the refusal rule signals when a ratio is meaningful. However there is no guidance on when to pick this tool over the sibling report tools, which are named in context but never referenced.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is in disclosing output semantics: the four verdict categories and the rule that conflicts are 'reported as a conflict, never averaged.' That is genuine behavioral context an agent could not infer from structured fields. It stops short of saying what happens with zero sources or how the verdict is surfaced in the response.

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?

Three short sentences, zero filler. The core operation and verdict set come first, the conflict-handling rule second, and the usage prohibition last. Every sentence carries information.

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?

With no output schema, the description does the necessary work of naming the verdict vocabulary and the no-averaging rule, which is exactly what an agent needs to interpret a result. The remaining gap is the shape of the input market document and what 'insufficient' is triggered by, but overall it is adequate for a single-parameter read-only tool.

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 applies, but the single parameter is documented only as 'Market document.' with nested content left entirely unspecified in both schema and description. The description adds no guidance on what the market object must contain for evidence to be resolvable.

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?

States a specific verb and comparison (weigh sources against the declared outcome) and enumerates the four verdict values, so an agent knows the tool produces an adjudication, not raw data. It does not name or distinguish itself from any of the listed siblings, which leaves differentiation implicit rather than explicit.

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?

Gives a clear negative boundary: 'Do NOT use to trade or to place a position,' which rules out a plausible mis-invocation for a prediction-market tool. The positive trigger (evaluate a resolver's sourcing before accepting an outcome) is implied rather than stated, and no sibling alternative is named.

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

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

Annotations already establish readOnly/non-destructive/closed-world, and the description adds real value on top: verification is done offline and 'nothing here reads a chain'. It does not say what a failed verification surfaces (throw vs. structured error list) or whether partial failures are distinguishable, which is a meaningful omission for a validator.

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?

Two sentences, front-loaded with the enumerated checks, then the usage condition and the exclusion. No filler, and the most decision-relevant content (what is verified, and what this is not) arrives first.

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?

With a nested, otherwise-undocumented receipt object and no output schema, the description does the heavy lifting by listing the invariants checked. The remaining gap is the return shape: an agent can't tell from the definition whether it gets a boolean, a verdict object, or a list of failure reasons.

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 two parameters are already documented, including the base64url-or-hex key format. The description still adds meaning by naming the receipt fields the verifier actually inspects (mandate expiry, amount, quantity*unit_price, refund), which the schema only calls an opaque 'receipt document as JSON'.

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?

Names a specific verb (verify/check) and resource (signed proof-of-spend receipt), then enumerates the exact validations performed: schema, Ed25519 signature, mandate expiry, positive amount, quantity*unit_price equality, refund ceiling. That level of specificity clearly separates it from the reporting siblings (reserve_report, reconcile_books, audit_spend).

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?

Gives an explicit trigger ('when an agent or provider returns a receipt and you need to know whether it actually proves the charge was allowed') plus explicit exclusions ('Do NOT use to move funds or to confirm a transaction on-chain'). Both the when and the when-not are stated, so the agent isn't left to infer.

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