Read the on-chain state of any ERC-8183 escrow job by ID (Open/Funded/Submitted/Completed/Rejected/Expired, client, provider, budget, deliverable hash). Job 39 is our verified live completion. Free.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Job ID (integer) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing safety and behavior. 'Read' explicitly indicates a non-mutating operation. It also mentions 'Free' (pricing/cost behavior) and lists the output fields, providing useful context about what the tool returns. It doesn't discuss rate limits or error handling, but for a simple read tool this is reasonable.
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 three short sentences: the first defines the core purpose and return fields, the second gives a helpful real-world example, and the third notes the tool is free. Every sentence adds value; 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?
The tool is simple (one parameter, no output schema), and the description adequately covers what the tool does and what it returns by listing the state fields. It also includes a known example (Job 39). Missing details like error behavior or exact response format are not critical for this simple tool, making it fairly complete.
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 only parameter job_id is already described as 'Job ID (integer)'. The description adds a concrete example ('Job 39 is our verified live completion') which gives additional context on how job IDs map to real jobs, but doesn't introduce new semantic details beyond the 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?
The description clearly states the tool reads on-chain escrow job state by ID, and enumerates the specific fields returned (status, client, provider, budget, deliverable hash). This specific verb+resource clearly distinguishes it from sibling tools like get_quote or get_attestation.
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 usage: use this tool whenever you need the state of an escrow job by ID. It says 'any' job, giving broad applicability. It doesn't explicitly name alternatives to avoid, but the read-only purpose is clear, and there are no exclusions stated.
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.
Most tools are clearly distinct (list, preview, sign, escrow state), but get_quote and call_paid_endpoint both return pricing and latency for endpoints, which could cause misselection. The three preview tools are similar but target different endpoints.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (call_, get_, list_, preview_, sign_). No camelCase or mixed conventions.
With 10 tools, the server is well-scoped for its purpose of endpoint discovery, quoting, previewing, and escrow verification. Each tool covers a distinct need without bloat.
The server lacks tools for actually executing paid endpoints or creating escrow jobs, and there is no way to list escrow jobs by client or provider. It focuses on planning and verification, leaving execution to external mechanisms, which is a notable gap for a trading-focused server.
