Pink Agentic AI Payments

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

With no annotations present, the description carries the full burden and does most of it: it declares the operation is side-effect-free ('Nothing is spent or held') and enumerates the return shape. It omits auth/credential requirements and any indication of what the decision trace contains or how costly the call is.

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 terse sentences, front-loaded with the most decision-relevant fact ('Dry run'), with zero filler. Every clause earns its place.

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 9-parameter tool with no output schema, the description usefully covers the return value (decision enum, rule, full decision trace) and the non-mutating guarantee, which is the essential behavior. The gap is routing guidance versus the sibling payment/rules tools.

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 89%, so the schema already documents nearly every parameter in detail — the local_hour text even explains its dry-run-only semantics and contrast with pink.request_payment. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 operation (dry-run policy evaluation) and the exact outcome vocabulary: would_allow / would_ask / would_block, plus the rule and decision trace. 'Nothing is spent or held' separates it from pink.request_payment, though it never names that sibling outright.

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?

'Dry run' implies the when-to-use context (preview a decision before committing), but the description never explicitly says to call this before pink.request_payment or when to reach for it over pink.list_rules. Usage must be inferred rather than read.

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?

No annotations are provided, so the description carries the full burden. It does disclose the scope of data exposed (a read of current spending limits) and the fields returned, but says nothing about permissions, data freshness, or rate limits.

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 dense sentence, front-loaded with the core purpose and then the returned fields; every clause earns its place with no filler.

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 zero-parameter read tool with no output schema, the enumeration of return fields gives the agent enough to know what it will receive. Minor gap: no note on whether values are live/authoritative.

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 tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate, and it correctly avoids inventing parameter 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?

The description states a specific verb+resource ('what this agent may still spend') and enumerates the concrete data returned (monthly budget left, spent today, single-payment cap, vault balances, company daily ceiling). This clearly separates it from siblings like check_policy or list_rules, though it never names an alternative directly.

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?

Usage is only implied: an agent can infer it should call this before spending to check remaining allowance, but there is no explicit when-to-use, when-not-to-use, or pointer to check_policy/list_rules for related checks.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the async approval flow (the credential appears only after a person approves) and that any payment_id is accepted, but it omits what is returned while still pending, whether polling is rate-limited, and any auth requirements — notable gaps for a mutation-adjacent status 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?

Three short sentences, front-loaded with the core action and return behavior, and no wasted filler. The closing sentence is brief and additive rather than redundant.

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 one-parameter tool with no output schema and no annotations, the description covers the essential return value ('returns the credential') but leaves the pending/not-approved state and error behavior unexplained. Adequate but with clear gaps for an agent deciding what to do on a non-credential response.

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% and the single hold_id parameter is already documented as 'hold_id / payment_id returned by pink.request_payment'. The description's 'also works for any payment_id' largely restates the schema, so the baseline 3 applies with no additional format or syntax 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 concrete action (check a pending payment) and the payoff (returns the credential once a person approves), which is clearer than the vague title 'Poll a hold'. It is distinguishable from pink.request_payment, the sibling that creates the hold, though the description never names that dependency explicitly.

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?

'Check a pending payment' implies the tool is used after a payment request has been made and before approval lands, but no when-to-use/when-not guidance or sibling alternatives are given. The agent must infer the polling lifecycle from the word 'pending' alone.

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?

No annotations are provided, so the description carries the full behavioral burden. It hints at a gating/approval behavior for payments but doesn't say whether the list is read-only, whether it requires auth, how fresh/stale the data is, or what it returns.

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 short sentences, front-loaded with the resource definition, with no wasted words. The second sentence adds behavioral color but is somewhat oblique.

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 zero-param list tool with no output schema and no annotations, the description should at least clarify the return shape or who can call it. It gives a useful domain hint (payment approval gate) but leaves an agent guessing about output and permissions.

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?

There are zero parameters, so the baseline is 4. The description correctly implies a no-input, company-scoped listing, matching the empty 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?

States the resource clearly: an approved list of suppliers, platforms and contractors. The verb 'list' is implied by the name, not spelled out in the description, which slightly weakens it, but the resource and scope are 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?

The second sentence ('Paying anyone else stops and asks a person') implies a workflow context involving payment decisions, and sibling tools like request_payment hint at the broader flow, but it never says when to call this versus check_policy or request_payment explicitly.

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?

With no annotations, the description carries the full burden. It usefully discloses evaluation semantics ('First match decides: allow, ask, or block') and timezone behavior for time-of-day rules, but says nothing about return shape, ordering stability, or whether the call is a safe read.

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, front-loaded with the resource and scoping. The timezone sentence is somewhat tangential but still earns its place by explaining a non-obvious field.

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 zero-parameter read tool with no output schema, the description does a good job explaining the meaning of returned rules (allow/ask/block, evaluation order, tz). Missing only a note about the read-only nature and result shape.

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 tool takes zero parameters, so the baseline of 4 applies. The description correctly focuses on output semantics rather than input parameters.

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 clearly identifies the resource ('the policy rules that apply to this agent') and adds scope ('in evaluation order'). It is specific but does not name or differentiate from the nearest sibling, pink.check_policy, which an agent could plausibly confuse it with.

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?

There is no when-to-use guidance and no mention of alternatives such as pink.check_policy. The agent must infer from context that this is a discovery/listing tool rather than a policy-evaluation tool.

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?

With no annotations, the description carries the full burden, and it does disclose one meaningful behavioral effect — that the call reconciles the payment and raises a trust score (a side effect worth knowing). It omits idempotency, whether duplicate filings are rejected, error behavior, and auth requirements for a mutation-style operation.

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 tight sentence with the precondition ('After paying') front-loaded ahead of the action and its benefit. No filler, though it is arguably under-sized for the tool's schema complexity.

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, no annotations, 0% parameter coverage, and a nested receipt object make the description insufficient: an agent cannot know what shape the receipt must take or what fields are mandatory within it. The stated trust-score benefit is the only extra context provided.

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% for two required parameters, one of which is a nested object with six sub-fields (url, note, total, currency, merchant, reference). The description names only the concept 'receipt or invoice' and says nothing about payment_id or any field format, so it fails to compensate for the total lack of schema documentation.

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 verb+resource (file the receipt/invoice) and situates it in a workflow step ('after paying'), which distinguishes it from sibling tools like request_payment. It does not name any sibling explicitly, but the action itself 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?

There is an implied precondition ('after paying'), which gives the agent timing guidance, and a stated purpose (reconciliation). However, no alternatives are named (e.g., what to do instead if no receipt is available), and no prerequisites such as required permissions or whether it can be re-filed are given.

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?

With no annotations, the description carries the full burden and does well: it enumerates the three outcome states and their payloads (a single-use credential, a hold_id while a human is asked, or a block reason), disclosing the human-in-the-loop flow. It also explains idempotency semantics for retries. It omits what happens after pending_human/blocked and any permission or side-effect context.

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 tight sentences with zero filler, and the outcome semantics are front-loaded. Every clause carries information an agent needs, and there is no redundant restatement of the schema.

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 10-parameter, high-stakes mutation tool with no annotations and no output schema, the description usefully covers return states. However, it leaves the follow-up flow unclear: what an agent should do with a hold_id for pending_human, and how the returned single-use credential relates to the sibling pink.get_credential.

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 90%, so the schema already documents nearly every parameter in detail, including the exact idempotency_key behavior. The description's only parameter-level addition, "Pass idempotency_key to make retries safe," repeats what the schema field already states more precisely, so baseline 3 is appropriate.

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 "The real call," which implicitly contrasts with the dry-run sibling pink.check_policy and, combined with the outcome states (allowed/pending_human/blocked), makes clear this is the tool that actually submits a payment. It never restates the verb+resource itself, leaning on the name and title, but an agent can still distinguish it from check_policy. Clear purpose without fully self-contained phrasing.

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?

Usage is only implied through "The real call" versus the check_policy dry run, and the note to pass idempotency_key for safe retries. There is no explicit statement of when to call this versus pink.check_policy or pink.get_credential, and no prerequisites or exclusions are given.

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