Foundry: prepaid AI compute in USDF

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

Goes well beyond the annotations: paid from USDF balance (never free credit), bounded by key/agent limits, max_price acts as a hard cap, failed non-2xx calls cost nothing, requires an API key, and returns the seller's answer plus a receipt. These are exactly the cost, auth, and failure semantics an agent needs before spending money.

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-loads the core purpose well, but the body is a dense wall of semicolon-linked clauses with some redundancy ('what one call costs and nothing on top' vs 'costs nothing') that makes it harder to scan than it needs to be.

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 still covers the return shape (seller's answer and receipt), cost/refund behavior, auth requirement, and the disabled-market error, leaving nothing essential for correct invocation.

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 real meaning: max_price is a cap that 'nothing [is] on top' of, and it clarifies that the input payload is forwarded to the seller and governed by the seller's own policy. That routing/interpretation context is not in 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?

States a specific verb and resource ("Calls a listing of the agents market by its id") and explicitly ties the id format to the sibling tool agents_market_search, so the agent can distinguish this from the search tool without opening either schema.

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?

Makes the search-then-call workflow clear by referencing where the id comes from and notes the 503 market_calls_unarmed condition, giving real context for when the call will or won't work. It stops short of stating explicit exclusions against sibling tools like quote or x402_pay.

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 declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds genuine context: searches need no key, prices are quoted in USDF drawn from this key's balance, and results are sorted by popularity/price/newest. It omits pagination and rate-limit behavior, which keeps it at 4 rather than 5.

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 long opening clause front-loads the resource and its return shape, followed by two short sentences on ordering and the sibling alternative. The field enumeration is dense but earns its place since no output schema exists, though it is on the verbose side.

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 usefully enumerates the fields each listing returns (id, name, tags, cost, I/O examples, data policy) and the sort/default and no-key behaviors. It is missing pagination guidance for limit/offset, which is the main gap for a 6-parameter search 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 67%, so the schema documents most parameters itself. The description restates the sort options and the id format but adds no meaning for q, tag, limit, offset or max_price beyond what the schema already provides, so the baseline 3 is warranted.

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 establishes the resource — a single market of agents, APIs and tools priced per call — and names the sibling (agents_market_call) that invokes one, so an agent can separate search from call. The verb 'search' is only implied from the name/title rather than stated, keeping it just short of a 5.

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 an explicit routing rule — 'No key needed to search; agents_market_call calls one' — which tells the agent when to search vs. invoke. It also notes the default ordering (popularity). It stops short of 5 because it never states when not to use search or how the other siblings (list_tools, list_models) differ.

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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: it explains what each returned figure represents (held funds for in-flight requests, remaining key budget, the signature-transfer allowance that funds x402 payments). It does not mention rate limits or refresh/latency characteristics, so not a 5.

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?

It is a single dense sentence-paragraph that covers both modes without waste, but the trailing clause 'which x402 payments come from' and the stacked parentheticals make it harder to parse than it needs to be. Front-loading is decent (key case first) but readability is compromised.

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 read-only, single-optional-parameter tool with no output schema, the description covers both invocation paths and what each returns in enough detail to call it correctly. It lacks nothing critical, though explicit guidance on what happens if both key and address contexts are present is absent.

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, and the description goes beyond it by explaining what the address parameter produces: on-chain USDF and USDG plus the spend allowance granted to the signature-transfer contract. It clarifies that supplying an address implies keyless mode, which the schema alone does not convey.

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 specifically what the tool returns: spendable amount, account balance, held funds, and remaining key budget under a key; or on-chain USDF/USDG plus transfer-contract allowance under an address. That is a clear resource ('balance') with two well-defined modes. It does not explicitly contrast itself with siblings like quote or x402_pay, so it falls short of a 5.

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 explicit conditions selecting each mode: 'With an API key' versus 'With address instead, and no key.' An agent can infer which invocation applies. However, it names no alternative tools or when-not-to-use cases, so it stops short of full routing guidance.

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 only give the safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false); the description goes far beyond, disclosing fund holding up front, refund mechanics in the paid asset, what happens at deadline and on disconnect, billing on provider usage vs. estimate, the no-cancellation rule, and the 20-second refusal with nothing charged.

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 core action and no filler sentences, but it is one long, undifferentiated paragraph with no headings or bullets, and the deadline/cut/refund behavior is restated several times (connection-close cut, paid-call deadline, provider-accepted-then-cut), which costs the reader on re-parse.

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 carries the return contract itself — text plus receipt fields, finish_reason "length" on truncation, structuredContent payment requirements on the first unpaid call, and the _meta receipt keys — which is exactly what an agent needs for a paid, non-idempotent, open-world call.

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, and the description adds real meaning on top: it establishes that payment applies only "with no key," that model ids come from list_models, and that the payment value may also arrive via _meta["x402/payment"] or the PAYMENT-SIGNATURE header rather than the named argument.

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?

"Runs a chat completion and returns the text with its receipt" is a precise verb+resource statement, and the scope (non-streamed, 4096-token output cap, paid per call) immediately separates it from read-only siblings like balance, list_models and receipt.

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 branches clearly on the two payment modes (API key balance vs. no-key x402/MPP), which is genuine usage guidance for this tool. However it never routes the agent to the siblings that exist for that purpose — quote/quote_tool for previewing the cost, balance for funds, receipt for retrieving receipts — so the agent must infer whether to call those first.

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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior: route availability is dynamic, and prices are only shown with an API key, including the USD/USDF pricing format. This is useful context beyond the structured annotations.

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 a single dense sentence that front-loads the main resource and lists the key output fields efficiently. It is slightly packed, especially the parenthetical pricing note, but no sentence is wasted.

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 zero parameters, no output schema, and only basic annotations, the description carries the necessary burden of explaining what is returned. It covers the model fields, dynamic route availability, and conditional pricing, so an agent has enough context to call it correctly.

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 has zero parameters, so there is no parameter semantics burden. The description correctly does not invent parameter details, and the 0-param baseline 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?

The description clearly identifies the resource (models served by the gateway) and the information returned (context window, output limits, route availability, conditional pricing). It does not explicitly differentiate this from the sibling list_tools tool, which is the main missing clarity point.

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 implied: use this to discover available models and their pricing/limits. However, there is no explicit guidance on when to choose this over siblings like list_tools, nor any stated preconditions beyond the API-key note for pricing.

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 declare read-only and non-open-world behavior. The description adds meaningful context beyond that: no key is needed to list, tool calls are paid from the same balance/key as chat, prices appear in USDF with an API key, every listed tool is callable now, and pages hold up to 200.

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 front-loaded with purpose and packs auth, payment, filtering, and pagination details efficiently. It is dense but every clause adds useful information, though the single paragraph is slightly overloaded.

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 low-complexity list tool with two optional parameters and no output schema, the description is complete. It covers what is returned at a high level, pagination, authentication, and pricing context.

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%, so the baseline is 3. The description reinforces q as filtering on id, title, or description and cursor as page.next, and adds the page-size limit of 200, which is useful but not extensive.

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: tools callable via POST /v1/tools/{id}, with payment context and ordering. This clearly distinguishes it from chat, list_models, and other siblings without needing to name 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?

Explains that it lists currently callable tools and describes q filtering and pagination, giving clear usage context. It does not explicitly name alternatives or say when not to use this tool, so it falls short of a 5.

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 only say readOnlyHint=true/openWorldHint=false, yet the description adds substantial context: it is an estimate and not a billing ceiling, actual billing follows provider-reported usage and is normally less, no key is required, and attested/private routing is quoted at the model's price on verified routes. This is exactly the kind of cost/auth behavior an agent needs beyond the structured hints.

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 dense sentences with no filler; the pricing semantics are front-loaded. Slight deductions for the roundabout opening noun phrase and the repeated 'at the model's price' clause, which make it less scannable than it could be.

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 still conveys the return's essence (dual USDF/USD figures, 4096-token cap) and the pricing model. However, it does not describe the shape of the returned quote or how the two currencies relate, leaving a modest gap for a tool whose whole job is producing a structured price estimate.

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 100% schema coverage the baseline is 3, but the description adds real meaning: 'Pass prompt or messages' clarifies the two mutually optional input paths, and the 'output capped at 4096 tokens' note relates to the token budget. The 4096 cap sits somewhat awkwardly next to the schema's max_tokens default/cap wording, creating mild ambiguity about which budget is meant.

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 defines the tool as 'the hold the chat tool places before running a request' and clarifies 'It is an estimate, not a ceiling', so an agent can infer this returns a pre-flight cost quote in USDF/USD for a chat request. It is distinguishable from siblings like chat, balance and receipt, though the purpose is expressed through a metaphor rather than a direct verb+resource statement.

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 states when this applies (before running a request, mirroring the chat flow) and gives input guidance ('Pass prompt or messages', 'No key needed'). It also names the conditions under which special routing pricing applies (attested hardware via ':private' or provider.private, Private-tier keys), but it never explicitly contrasts with an alternative tool or states when not to use it.

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 declare readOnlyHint=true and openWorldHint=false, yet the description still adds real value: it validates the input exactly as the real call would, runs nothing, and holds no funds — key facts for a cost-estimation tool. This is meaningful disclosure beyond the annotation set.

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 sentences that are front-loaded but grammatically muddled — 'What a call to a tool would hold for this input before it runs (its most it can cost)' reads awkwardly, and the USDF/USD duality is unexplained. It is short but not clean.

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 usefully characterizes the return: the maximum cost in USDF and USD plus the tool's price. It also covers the auth requirement and the no-side-effect guarantee, leaving little an agent needs but doesn't have.

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 both parameters are documented in the schema (tool id from list_tools, input matching the tool's input schema). The description adds no syntax or format detail 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?

Names a specific verb (quote) and resource (a call to a tool) and states the output dimension (cost in USDF and USD). It does not, however, distinguish itself from the sibling tool named simply 'quote', leaving ambiguity about which quoting tool to pick.

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?

'Before it runs' implies the pre-flight use case, and 'No key needed' tells the agent it can be invoked unauthenticated. There are no explicit when-not conditions and no comparison against the sibling 'quote' tool, so the routing guidance is only implied.

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 declare readOnlyHint=true and openWorldHint=false, so the safe-read profile is covered. The description usefully adds that the credential changes the scope of the result, that settlement fields appear only 'once settled' (eventual availability), and names the backing endpoint GET /x402/v1/receipts/{id}; it says nothing about error behavior 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?

The mode distinction is front-loaded, which is good, but the second half is a comma-spliced pile-up of nouns ('the usage, the price sheet version, the cost and, once settled, the settlement, its transaction and the rows behind the onchain digest') that is hard to parse in one pass.

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?

There is no output schema, so the description carries the burden of explaining what comes back, and it enumerates the returned fields for both modes plus the endpoint. For a single-parameter read tool this is close to complete, with only error/empty-settlement handling left implicit.

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 parameter and 100% schema description coverage, the schema already explains that request_id is the id returned with the completion (and the x-request-id header). The description only echoes 'request id' and the endpoint path, adding no format or constraint detail 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 states a specific resource (a request's receipt) and enumerates its contents: usage, price sheet version, cost, settlement, transaction, and onchain digest rows. It clearly distinguishes two retrieval modes (own request via API key vs. public receipt of any id), though it never names a sibling to contrast 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?

It gives explicit conditions for the two modes: 'With the API key that made the request' versus 'With no key: the public receipt of any request id, x402 ones included.' This tells the agent which invocation applies, but offers no guidance against alternatives such as balance or quote.

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 only declare readOnly=false, openWorld=true, idempotent=false, destructive=false; the description adds substantial behavior beyond that — how billing works (USDF charge covering seller amount plus payer fee, never free credit), settlement semantics (charged only once the chain shows it, an unsettled payment costs nothing), and the return content (seller answer plus payment and receipt). This is exactly the kind of financial/consequence disclosure an agent needs before invoking a money-spending call.

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 core action and the payment model, then quote behavior, then discovery pointer — a sensible ordering. The single dense paragraph packs in a lot, and the closing list_tools pointer is slightly buried, but no sentence is 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?

With no output schema, the description correctly describes the return ('the seller's answer with the payment and its receipt') and covers auth, billing, and settlement risk for a 7-parameter mutating tool. It leaves the caller to infer request-body/method edge behavior and error outcomes (e.g., what happens on insufficient balance).

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%, so the baseline is 3. The description explains the quote parameter's effect, but that largely restates the schema's own text ('Answer the price and pay nothing'), and it adds nothing for method, body, headers, network, or max_price — all of which are already documented in 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?

States a concrete verb and resource — 'Calls a URL that asks for an x402 payment and pays it for you' — and immediately clarifies the settlement model (gateway pays seller in USDC from float, charges the key in USDF). An agent can distinguish this from sibling tools like quote or balance without inspecting the schema.

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 explicit conditions: 'quote: true answers what it would cost and pays nothing' and points to list_tools with the marketplace source for discovering callable third-party URLs. Prerequisites (needs an API key, operates within key and agent limits) are stated. It stops short of naming when to use the sibling quote/quote_tool tool instead of the quote parameter.

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