Describe the planned free receipt-verification tool contract.
This is intentionally marked not-live until `/v1/receipt-verify` is implemented
and backed by payment-edge audit/state reconciliation.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| receipt_hash | Yes |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool's not-live state and dependency, which is transparent. However, it does not explicitly state whether the tool is read-only or what side effects exist, leaving some ambiguity.
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 purpose, and a clear condition. Every sentence earns its place with no wasted words.
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 has 2 parameters and no annotations, the description is incomplete. It lacks explanation of how to use the parameters, what the output looks like (though output schema exists, description could still help), and any prerequisite knowledge. The not-live status is helpful but not enough.
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 0% (no parameter descriptions in schema). The description does not add any meaning for the two parameters (order_id, receipt_hash). The tool description should explain what these parameters represent in the context of the receipt-verification contract.
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 clear verb ('describe') and resource ('planned free receipt-verification tool contract'). It distinguishes itself from operational sibling tools like ddg_order_status by being a design/planning tool. However, 'describe' could be more specific (e.g., returns a schema or documentation).
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 explicitly states that the tool is 'not-live' until a certain backend is implemented, giving clear guidance on when NOT to use it. It implies use for planning/review but does not list alternative tools for the actual operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose, ranging from status checks to order management to payment processing. Despite the large number, descriptions make them easy to differentiate, with no obvious overlap.
All tools share the 'ddg_' prefix, but naming patterns vary: some use verb_noun (e.g., ddg_list_models) while others use noun_noun (e.g., ddg_agent_status). This mix reduces consistency, though readability remains acceptable.
With 25 tools, the count is at the high end but scales to cover diverse aspects of payable services (status, orders, payments, models, x402). Minor consolidation could be possible, but most tools earn their place.
The tool surface covers core workflows like order lifecycle, payment, and service discovery. Minor gaps (e.g., no cancellation or refund tools) exist but do not severely hinder typical agent interactions.