agent-embassy

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

Beyond the annotations, the description discloses critical behaviors: the call is monetized via x402 with a specific cost and network, issuance depends on principal verification, and the result ties an operator to a public key with an expiry. It also gives the exact endpoint, which is highly actionable.

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 sentences and every sentence earns its place: definition, failure behavior, and payment/endpoint. Key information is front-loaded 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?

The description covers the endpoint, payment, the core security property, and the output schema exists, but the low parameter coverage leaves important invocation details unexplained. For a tool with 8 required parameters, the absence of guidance on principal kinds and attestation methods makes it not fully self-sufficient.

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 only 9%, so the description carries the burden of explaining parameters. It provides a high-level conceptual mapping ('agent's public key', 'operator details', 'expiry', 'verified principal') but does not explain key required parameters such as principal_kind, principal_attestation_method, agent_key_scheme, or idempotency_key. An agent would struggle to choose valid values.

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 verb ('Issue') and resource ('Agent ID'), and explains what the tool produces: a signed identity attestation binding an agent's public key to a verified principal. It does not explicitly compare itself to sibling tools like agentid_renew or agentid_verify, so differentiation is clear from context rather than stated.

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 this is for issuing a new Agent ID and emphasizes that issuance is refused when the principal cannot be verified. It does not explicitly state when to use this tool versus agentid_renew, agentid_verify, or agentid_revoke, nor does it describe prerequisites beyond verification and payment.

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?

The annotations declare openWorldHint=false, but the description explicitly says it is monetized via x402, requires an external POST to https://agent-embassy.fly.dev/v1/agent-id/renew, and involves a $0.25 USDC payment on Base or Arbitrum One. This is a direct contradiction with the closed-world annotation, so the behavioral transparency score is 1.

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 sentences, front-loaded with purpose, then auth prerequisite, then endpoint and payment details. Every sentence earns its place, though 'paid tool, not free' and 'x402 payment' are slightly redundant, preventing a 5.

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 endpoint, auth requirements, payment amount, and renewal behavior are all stated, and an output schema exists, so return values need no explanation. However, optional parameters remain under-described, and the openWorldHint contradiction leaves an unresolved behavioral inconsistency that reduces completeness.

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 only 20%, so the description must compensate, but it only meaningfully contextualizes revocation_signature via the signature requirement and hints at validity_days through 'new expiry'. agent_id is self-evident, yet idempotency_key and validity_days constraints remain under-specified.

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 and resource: renew an Agent ID, issue a fresh Agent ID with the same identity chain, and retire the old one. This clearly distinguishes it from sibling tools like agentid_issue, agentid_revoke, and agentid_verify.

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 tells the agent this is for renewing before expiration, requires the same principal-or-Embassy signature as retiring, and is a paid tool. It does not explicitly name sibling alternatives or give an exclusionary 'do not use for X' rule, so it falls just short of perfect 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 already carry readOnly=false, idempotent=true, destructive=false, but the description adds meaningful beyond-annotation traits: the tool is monetized ($0.25 USDC via x402), payment networks are specified (Base or Arbitrum One), and the persistent effect is disclosed (retired ID reports revoked on every later check). It stops short of describing failure/error behavior or explicit irreversibility, which is why it is a 4 rather than 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?

Four tight sentences, each earning its place: purpose+requirement, persistent effect, monetization+endpoint+pricing. The purpose is front-loaded and there is zero filler, making it easy for an agent to extract the critical call facts quickly.

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?

An output schema exists, so return values need not be described in prose. The description covers the essential operational facts an agent needs before calling: authentication requirement, payment amount and network, the persistent consequence, and the endpoint. The notable gap is the unresolved parameter-semantics gap for required fields, which keeps this below a 5.

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 only 20% — only agent_wallet is documented. The description partially compensates by explaining the provenance of revocation_signature (from accountable principal or Embassy) and the payment context of the tool, but it adds nothing about agent_id, reason, or idempotency_key. With low schema coverage, the description must carry more weight and it does not.

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 a specific verb-resource pair, "Retire an Agent ID instantly," which unambiguously states the operation. It also distinguishes itself from lifecycle siblings (agentid_issue, agentid_renew, agentid_verify) because retire/revoke is a distinct phase, and the signature-requirement clause adds scope precision.

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 context (retire an Agent ID within a lifecycle) and states the prerequisite for legitimate use (signature from accountable principal or Embassy for cause), which is useful. It never names sibling alternatives or says when NOT to use this tool, leaving the agent to infer the revoke-vs-renew/verify choice.

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 provide idempotentHint=true and readOnlyHint=false, but the description adds significant behavioral context: the identical response shape for all statuses, the 'unknown' handling without errors, and the monetization via x402 with payment details. These go beyond annotations and help the agent understand side effects (payment) and error behavior.

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 block but efficiently front-loads the core purpose before adding response shape, monetization, and endpoint details. It is longer than minimal but every sentence adds value, with no redundancy. The structure flows logically from what to how to payment.

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's simplicity and the presence of an output schema, the description covers the key aspects: statuses, response shape, error behavior, payment requirements, and endpoint. It does not explain the parameters, but the output schema and the tool's self-evident purpose reduce the need. It is complete for an agent to invoke 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?

Schema description coverage is only 33% (only agent_wallet is described). The description does not explain agent_id or idempotency_key, which are required. While agent_id is self-explanatory from the tool name, idempotency_key is a common but not universally understood parameter. The description does not compensate for the low schema coverage, leaving a gap in parameter meaning.

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 and resource: 'Check an Agent ID's current standing' with explicit statuses (valid, revoked, expired, unknown). It clearly distinguishes from sibling tools like agentid_issue, renew, and revoke by focusing on verification. The response shape is also described, making the tool's purpose 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 description clearly implies when to use the tool (to check status) and provides context about unknown IDs never erroring. However, it does not explicitly mention alternatives or when not to use it. Since the purpose is obvious and it names no exclusion conditions, it is clear but lacks explicit sibling differentiation.

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?

The description adds meaningful context beyond annotations by disclosing the x402 payment requirement, the $0.25 USDC cost, and the supported chains. However, it does not explain what 'prove what happened' means operationally or what the response behavior is. It does not contradict the 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 brief and front-loaded with purpose and payment details. No filler is present, though the opening sentence could be more specific about what an assurance check produces.

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?

Despite the presence of an output schema, the description is incomplete for successful invocation: required parameters are undocumented, the payment integration is only partially described, and no usage context or behavioral expectations are covered. An agent would struggle to construct a valid request without additional information.

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% and the description does not explain any of the six parameters. It only indirectly relates to amount_usdc and provider_endpoint. Required fields like idempotency_key and permissions_requested are left entirely unexplained.

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 names a specific endpoint and action: paying via x402 for work and proving what happened. The purpose is recognizable, though the phrase 'prove what happened' is somewhat vague. It does not explicitly distinguish itself from siblings like verified_check or trust_report.

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 only usage guidance is that the tool is paid and not free, which implies a cost consideration but does not say when to choose this tool over alternatives. No exclusions, prerequisites, or sibling routing are provided.

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?

The description adds a crucial non-obvious behavior beyond the annotations: the tool is monetized via x402, costs $0.25 USDC, and runs on Base or Arbitrum One. This is exactly the kind of auth/payment context annotations don't carry. It does not contradict the existing idempotent or destructive 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?

The description is compact and puts the payment detail in the second sentence, but the first sentence is vague and wastes the front-loaded position on imprecise language. Brevity helps, yet clarity suffers because the core purpose is missing.

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?

Even with an output schema present, this is a paid endpoint with four parameters and no functional explanation. An agent cannot determine what compute_alerts does, when to pick it, or how to populate gpu and limit. The cost disclosure is helpful, but the overall definition is insufficient 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 description coverage is only 25%; gpu, limit, and idempotency_key are entirely undocumented in the schema. The description adds nothing about these parameters, forcing agents to guess their semantics. With such low coverage, the description should compensate but instead ignores parameters completely.

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 'Agents pay for work and prove what happened,' which is ambiguous and never mentions alerts, the tool's namesake. It names an endpoint and payment method, but not what the tool actually does or produces. This is too vague to distinguish from sibling compute tools.

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 guidance on when to use compute_alerts versus compute_history or compute_spot_prices. The description only warns that the tool is paid; it does not state criteria, alternatives, or exclusions. An agent is left without a basis for selection.

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 provide readOnlyHint=false and idempotentHint=true; the description adds useful payment behavior: it is paid, costs $0.25, uses USDC on Base or Arbitrum One, and requires x402. However, it does not disclose side effects, idempotency expectations, or what happens after payment, which matters because readOnlyHint is false. No contradiction with 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 short and mostly to the point, but it contains redundancy: 'MONETIZED VIA x402', 'paid tool, not free', and 'with an x402 payment' repeat the same idea. The main endpoint is placed at the end of the third sentence and the opening sentence is vague rather than a precise summary of the tool's function.

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 4 parameters, only one required, and a low schema-coverage rate, the description leaves too much to inference. It supplies payment routing but omits parameter semantics, usage conditions, and side-effect expectations. Since the output schema exists, return value documentation is not needed, but the other gaps are material enough that an agent could call the tool incorrectly.

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 only 25% and the description provides no parameter explanations. Required idempotency_key, gpu, limit, and agent_wallet are never described in the prose; only agent_wallet has a schema note. The description mentions payment amounts but does not help the agent understand how to populate any field.

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 does not state a concrete verb or resource; 'Agents pay for work and prove what happened' is vague and could describe payment, proof, or history retrieval. The endpoint path is the clearest clue, but the description never says it lists or retrieves compute history. It also does not differentiate compute_history from siblings like compute_spot_prices or compute_alerts.

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 gives payment and endpoint details but no guidance on when to use this tool versus compute_spot_prices, compute_alerts, or other siblings. There are no conditions, exclusions, or alternative-selection hints. The only usage signal is that the tool is payable, which is not enough to route an agent correctly.

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?

The description adds valuable non-obvious behavioral context: the tool is monetized via x402 and costs $0.25 on Base or Arbitrum One, which the annotations do not convey. It also identifies the exact endpoint. It doesn't cover failure modes or rate limits, but annotations already cover idempotency and non-destructiveness, so the added payment/endpoint context is meaningful.

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 short, but the opening sentence 'Agents pay for work and prove what happened' is vague and does not earn its place. The payment and endpoint sentences are direct, but the structure would be improved by leading with the tool's actual function.

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?

Although an output schema exists and the payment mechanism is described, the description omits all parameter semantics, does not state what data is returned, and gives no hint about when to prefer this tool over compute_alerts or compute_history. For a tool with five undocumented optional parameters, this is insufficient for confident 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?

With 0% schema description coverage and five optional parameters, the description should explain what gpu, type, min_gpus, verified, or max_results control. It says nothing about any parameter, so an agent cannot infer valid values or semantics from the description.

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 never explicitly says the tool returns spot prices or compute market rates. It opens with 'Agents pay for work and prove what happened,' which is about payment/proof, not pricing, and the only resource hint is the URL path. This leaves the actual function vague and dependent on the title rather than the description.

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 guidance about when to use this tool versus compute_alerts, compute_history, or any other sibling. The only usage information is the payment prerequisite ($0.25 via x402), which is a requirement, not a selection criterion.

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 indicate idempotent, non-read-only, non-destructive behavior. The description adds critical context beyond that: the tool is paid, costs $0.25, and requires x402 payment on specific networks. This is valuable because an agent must know a financial charge is incurred.

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 short, but the opening sentence 'Agents pay for work and prove what happened.' is vague and partly repeats the payment information in later sentences. The useful endpoint and cost details could be more tightly front-loaded.

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 paid tool with two required parameters and zero schema documentation, this description is incomplete: it omits the meaning of both parameters and provides no usage scenario. Payment details are useful, but the tool is not safely invocable without parameter semantics.

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% and the description names neither parameter. The required fields 'url' and 'idempotency_key' are left unexplained, so an agent cannot determine what URL to supply or how idempotency is expected to work.

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 names an action ('prove what happened') and a paid POST endpoint, but 'work' and 'what happened' are vague. It never explicitly says this tool returns compute history, despite the title, and does not distinguish itself from the sibling compute_history.

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 explains that the tool is monetized via x402 and gives the endpoint and cost, but gives no guidance on when to use this tool versus alternatives like compute_history or trust_report. There are no selection criteria, exclusions, or alternative suggestions.

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 indicate idempotentHint=true and readOnlyHint=false, so the description doesn't need to repeat those. The description adds genuinely useful behavioral context: the tool is paid via x402 and the exact amount/chain. It also discloses the endpoint. However, it doesn't disclose side effects beyond registration, failure behavior, or what happens to the recovery blob, which is a moderate gap.

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 brief and has no filler. It front-loads the purpose and then gives the endpoint and payment info. Each sentence adds information. It could be improved by adding parameter semantics, but for pure conciseness it scores well.

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 an output schema, so return values don't need description. The description covers purpose, endpoint, and payment. But the low schema coverage leaves parameter semantics missing and there is no mention of error cases or post-registration behavior. For a non-read tool with 4 required params, this is adequate but incomplete.

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 very low at 17% (only 'dev mode only' for agent_wallet is described in schema). The description itself adds no parameter-level meaning: it doesn't explain contact_name, quorum_rules, recovery_blob, or idempotency_key semantics beyond their names. With low coverage, the description must compensate and it doesn't.

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 and resource: 'register' a recovery, and clearly notes the monetization mechanism. It somewhat distinguishes the action by naming the exact endpoint and payment requirement, though it doesn't explicitly contrast with sibling tools. For a registration tool with no obvious sibling conflict, this is clear enough.

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 implicitly says when to use it: agents paying for work and proving what happened, with the payment requirement. It does not explicitly state when not to use alternatives or mention any sibling alternatives. The context is sufficient to understand the moment of use, but the exclusion/alternatives guidance is missing.

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?

The description adds transparency beyond annotations by disclosing that the tool is paid via x402, costs $250, and requires a POST to a specific endpoint. This is useful behavioral context. However, it does not explain the effects of calling the tool (e.g., what happens on success or failure), the role of the idempotency key, or any side effects beyond payment. The annotations already indicate it is a non-read-only, idempotent operation, so the description does not contradict them.

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 concise, consisting of two sentences, and includes the endpoint and payment details efficiently. However, it is not front-loaded with the tool's primary purpose; the first sentence is vague and does not orient the agent. The structure is compact but sacrifices clarity for brevity.

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's complexity (paid, 5 parameters, low schema coverage, output schema present), the description is incomplete. It does not state the tool's core function, the meaning of key parameters, or the expected input/output relationship. While the output schema exists, the description still needs to convey the purpose and invocation context, which it fails to do. The agent would be left uncertain about what to pass and what to expect.

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 only 20% (only agent_wallet has a description). The description does not clarify the meaning or purpose of any parameter, including required ones like paper_id and idempotency_key. It does not compensate for the low schema coverage, leaving the agent to infer parameter semantics from names alone, which is insufficient for correct invocation.

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 a vague statement about paying for work and proving what happened, which does not clearly identify the tool's function. The name 'research_paper' suggests it produces or processes a research paper, but the description never states this directly. It focuses on payment mechanics rather than the core action, leaving the agent to guess what the tool actually does.

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?

No guidance is provided on when to use this tool versus its siblings, nor are any prerequisites or exclusions mentioned. The description does not mention alternatives like prove_it or verified_check, and the payment detail is the only context. An agent would have no basis for selecting this over other tools.

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 idempotentHint=true and destructiveHint=false, so the description does not need to repeat those. It adds meaningful behavioral facts beyond the annotations: requires x402 payment, costs $0.25 in USDC on Base or Arbitrum One, and uses POST to a specific endpoint. It does not describe failure modes or what exactly is stored, but the payment and side-effect implications are clearly disclosed.

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 short and front-loaded with the core idea, then gives payment and endpoint details. The all-caps 'MONETIZED VIA x402' is slightly noisy, but each sentence carries useful information and there is little wasted text.

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 paid mutation tool with three parameters and an output schema, the description leaves important gaps: it does not clarify the meaning of url, the purpose of idempotency_key, or the shape of the proof/report being returned. Payment mechanics are covered, but an agent still cannot confidently construct a correct call without more parameter 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 only 33%: only agent_wallet has a description, while url and idempotency_key do not. The description does not explain what url should contain, what idempotency_key is for, or how the x402 payment maps to parameters. With low schema coverage, the description needed to compensate and did not.

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 says 'Agents pay for work and prove what happened' and gives the POST endpoint, so an agent can infer that this tool is about paying for and reporting/proving work. However, it never states a clear verb+resource such as 'creates a trust report' or 'submits proof of work,' and it does not distinguish this from the sibling verified_check.

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 gives useful context: this is a paid tool, costs $0.25, and is monetized via x402, so agents should only call it when payment is possible. It does not mention when to use this tool versus alternatives like verified_check or compute_history, and it gives no when-not-to-use 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?

The description discloses that the tool is monetized via x402, costs $0.15, and specifies the POST endpoint. This adds valuable behavioral context beyond the annotations (which already indicate it is not read-only, is idempotent, and non-destructive). However, it does not explain side effects, return behavior, or failure modes, so it only partially carries the transparency burden.

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 short but not well-structured. It opens with a vague statement ('Agents pay for work and prove what happened') before jumping into payment details and the endpoint. It does not front-load a clear purpose statement, and the key action of the tool is not summarized upfront.

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 7 parameters with minimal schema descriptions, an output schema (not visible here), and no usage context, the description is severely incomplete. An agent cannot determine what the tool actually checks, what the expected inputs mean, or what it returns. The description only covers payment and endpoint, leaving the agent to guess the tool's behavior.

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 only 14% (only agent_wallet has a description, 'dev mode only'), and the tool description provides no explanation of url, idempotency_key, expect_status, expect_json_path, expect_json_equals, or expect_body_contains. With such low schema coverage, the description was expected to compensate, but it does not address any parameter semantics.

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 says 'Agents pay for work and prove what happened' which is vague and does not clearly state the tool's verb and resource. It does not explicitly say that it verifies a URL's status or body content against expectations, nor does it distinguish itself from sibling tools. The title 'Verified Check' hints at verification, but the description leaves the core purpose ambiguous.

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 guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or why an agent should pick it over compute_alerts, trust_report, etc. The payment note is about cost, not usage context.

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