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

The description claims to return a TypeScript snippet (code generation) but also says 'accept a provider quote and lock USDC in escrow', which implies performing an on-chain action. This ambiguity about side effects (code generation vs. actual execution) is misleading. Annotations do not clarify; readOnlyHint=false and destructiveHint=false are consistent with code generation but inconsistent with actual locking.

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 efficiently convey purpose and usage condition without extraneous detail. Every sentence 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?

Given the tool has 3 parameters, no output schema, and minimal annotations, the description covers purpose, required parameters, and a usage condition. It lacks clarity on whether the tool actually executes an action or just generates code, which is a notable gap. Otherwise adequate.

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 description mentions txId and quotedPrice are required and adds context that quotedPrice is the agreed USDC amount. However, the schema already describes these parameters adequately (coverage 67% per context signals). The description adds marginal value 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 it returns a TypeScript snippet to accept a provider quote and lock USDC in escrow, with a state transition from QUOTED to COMMITTED. This distinguishes it from siblings like agirails_submit_quote (provider side) and agirails_get_transaction (viewing).

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 says 'Only generate this code after reviewing the quote from agirails_get_transaction', providing a clear when-to-use guideline. Could be improved by also stating when not to use, but the guidance is specific and actionable.

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 indicate destructive and non-read-only behavior. The description adds that it returns a snippet and cancels transactions, but doesn't disclose potential side effects, required permissions, or what happens to escrowed funds beyond returning 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?

Two concise sentences with no filler. Front-loaded with the main purpose, then elaborates on specifics.

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 no output schema, the description explains the return type (TypeScript snippet) but lacks detail on the snippet's structure or error handling. Parameter info is covered by schema. Minimal completeness for a low-complexity 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 50% (only txId has a description; network has enum/default but no description). The description adds no parameter info, so it doesn't compensate for the missing 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 clearly states the tool returns a TypeScript snippet to cancel transactions and specifies the allowed statuses (INITIATED, QUOTED, COMMITTED). This verb+resource+scope is distinct from sibling tools like agirails_accept_quote or agirails_deliver.

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 explicit guidance on when to use this tool vs alternatives, or prerequisites like having a transaction ID. The description implies use for cancellation but doesn't exclude cases or mention 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 are neutral (readOnlyHint=false, destructiveHint=false), but the description adds critical behavioral context: executing the returned snippet triggers the dispute window. This goes beyond annotations by disclosing a side effect.

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 with no redundant information. The first sentence states the core purpose and state transition; the second adds the critical side effect. Every word 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?

Given the lack of output schema, the description sufficiently covers purpose, side effects, and deliverable hints. It does not detail the return format of the snippet, but the tool's purpose (generating code) is clear. Additional information about how to execute the snippet would improve completeness, but it is already adequate.

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 schema covers txId and deliverable with descriptions, and network with an enum. The tool description adds examples for the deliverable parameter ('result, CID, URL, or summary'), providing extra meaning beyond the schema. Parameter coverage is 67%, and the description compensates well.

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?

Description clearly states it returns a TypeScript snippet to mark a transaction as delivered, specifying the state transition (IN_PROGRESS → DELIVERED) and what the deliverable includes (result, CID, URL, or summary). This differentiates it from sibling tools like agirails_dispute or agirails_settle.

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 is tailored for providers delivering a service, but does not explicitly exclude when not to use it or compare to alternatives. It provides clear context: running the code triggers the requester dispute window, which is useful for decision-making.

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 indicate destructiveHint=true, but the description clarifies the tool only returns a code snippet, not directly mutating state. It adds context about the 5% bond and 24-72 hour oracle resolution, going beyond what annotations provide.

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 with no wasted words. The main purpose is front-loaded, and the usage guidance follows naturally.

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 adequately explains what the tool returns (a TypeScript snippet) and when to use it. However, it lacks details on how to handle the snippet (e.g., execution), but for a code generation tool, this is acceptable. No output schema exists, so the description bears the burden.

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 67% (txId and reason have descriptions; network only has enum). The description does not add any additional parameter meaning beyond the schema, so it meets the baseline with minimal extra value.

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 it returns a TypeScript snippet to raise an AIP-14 dispute, specifying the state transition and bond details. It distinguishes itself from sibling tools like agirails_settle or agirails_deliver.

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 says 'Use when delivery does not match the covenant/deliverables,' providing a clear use case. It does not explicitly explain when not to use it, but the context implies alternatives like settle are for matching deliveries.

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 idempotentHint, indicating safe read operation. Description adds no behavioral traits beyond that, but no contradiction.

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?

One long sentence with a comma-separated list of concepts. Adequate but not concise; could be organized into bullet points or shorter phrases.

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?

Covers purpose and concepts, but lacks output format details (e.g., returns text or markdown). Given no output schema, description should hint at return structure.

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 has 100% coverage for the single parameter, listing possible values. Description repeats some values but adds no new meaning or format details beyond 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 it explains AGIRAILS/ACTP concepts with documentation context, listing specific concepts. This distinguishes it from sibling tools that perform actions (e.g., accept, cancel).

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 use for explanation, but lacks explicit when-to-use vs alternatives like agirails_search_docs. No guidance on when not to use or prerequisites.

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 and idempotentHint, indicating a safe read operation. The description adds value by specifying the return data fields (address, pricing, covenant, etc.), which is beyond the annotations. No contradictions.

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 with two sentences: one for purpose and one for search methods and return data. It is front-loaded with the purpose. However, it omits details on the remaining two parameters, which would have been valuable but doesn't fit the conciseness criterion.

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 no output schema, the description does mention the return data (Agent Card v2). However, it lacks completeness by not describing all parameters (limit, network) or any pagination behavior. The tool has reasonable complexity with 4 optional parameters, so more detail would improve 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 0%, so the description must compensate. It mentions two parameters (capability and keyword) but omits limit and network. The provided examples ('translation', 'data analysis') add some context, but the description fails to explain the default values and enum for network and the purpose of limit.

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 discovers AI agents on the AGIRAILS network and returns Agent Card v2 data. It specifies search methods (by capability or keyword), distinguishing it from sibling tools like agirails_get_agent_card which retrieves a specific agent.

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 when to use the tool (searching for agents by capability or keyword). It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select this tool over siblings like agirails_get_agent_card.

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 idempotentHint. The description adds significant detail about the returned data: covenant (accepts/returns schema + guarantees), SLA, pricing, payment modes, on-chain verification. This fully discloses the tool's output beyond what annotations cover.

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: first states the core action, second lists key return fields and usage tip. No fluff, front-loaded with verb and object.

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 simple get tool with one parameter and no output schema, the description fully covers purpose, usage context, return structure, and how to get the input. Nothing is missing given the tool's simplicity.

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% with a good description of the slug parameter. The tool description adds cross-reference to agirails_find_agents for context, which helps the agent understand how to obtain the slug. While not extensive, it adds practical value.

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 'Fetch the full Agent Card for a specific agent,' using a specific verb and resource. It distinguishes from sibling tools like agirails_find_agents by indicating this tool returns detailed card data for a known agent, while find_agents lists agents.

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 says 'Read this before requesting a service,' providing explicit when-to-use guidance. It also references agirails_find_agents for obtaining the slug, but does not explicitly state when not to use or list alternatives.

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?

Beyond annotations (readOnlyHint, idempotentHint), the description reveals the output is a TypeScript snippet (not raw data), which is critical for correct agent behavior. No contradictions 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?

Single sentence that effectively communicates the tool's purpose, output type, and usage hint. 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 simple input schema (1 optional param) and no output schema, the description covers the key points: what the tool returns, its content, and a practical usage tip. Slightly missing parameter detail but overall complete for its complexity.

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, the description does not explain the 'network' parameter. However, the parameter is simple (optional enum with default), and the schema alone is sufficient. The description adds no additional semantics, meeting the baseline.

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?

Description clearly states the tool returns a TypeScript snippet to get USDC balance, listing components (total, locked, available). This verb+resource structure distinguishes it from siblings, which are primarily actions (accept, cancel) or other queries (get_transaction).

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?

Includes explicit advice: 'Run the generated code before committing to transactions,' indicating when to use. While no explicit alternatives or when-not scenarios are given, the context from sibling tools and read-only annotations makes it clear this is a preparatory read operation.

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 idempotentHint. The description adds that reading makes the AI a network participant, which is a useful behavioral detail.

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 the main action, no unnecessary words. Every sentence adds value.

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, but description indicates it returns 'the full protocol specification', which is sufficient for this simple fetch 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?

No parameters exist, and schema coverage is 100%. The description does not need to add parameter details, meeting the baseline for zero-parameter tools.

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 action ('Fetch the full AGIRAILS.md protocol specification') and the resource, distinguishing it from sibling tools that involve actions like payments or cancellations.

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 says to use it to understand the protocol, but does not mention when not to use or alternatives, though the context makes it clear.

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 idempotentHint, covering safety. The description adds that it returns 'copy-paste ready code,' which is useful behavioral context. No contradictions, but no further traits 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?

Two sentences, direct and front-loaded. No unnecessary words; every sentence serves a purpose.

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 simple tool with 3 optional parameters and no output schema, the description provides enough context: purpose, return type, and usage hint. Missing network mention, but not critical given defaults.

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%, so description carries burden. It mentions intent (earn/pay) and language (TypeScript/Python) implicitly, but does not cover the network parameter. Partially adds meaning but not fully compensates.

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?

Clearly states it provides runnable TypeScript/Python code for earning or paying USDC via the AGIRAILS SDK. Differentiates from siblings like agirails_pay or agirails_request_service by focusing on getting started code rather than executing actions.

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?

Explicitly says 'Use when someone wants to get started quickly,' providing clear context. However, it does not mention when not to use this tool or suggest alternatives like agirails_pay for actual payments.

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 idempotentHint=true, so the description does not need to cover safety. It adds value by listing the specific data returned (status, escrow balance, next action hint, metadata), providing more behavioral context beyond 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 a single sentence that is concise, front-loaded with the key action and output, and contains no unnecessary 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, no output schema, and safe annotations, the description covers the main purpose and return information. It could mention the network parameter's purpose or the snippet's format, but it is still sufficient for a simple getter 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?

With 50% schema description coverage, the schema already documents txId and network parameters. The description does not add new semantics beyond the schema, but it does not detract either. 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 clearly states it returns a TypeScript snippet with full transaction details (status, escrow balance, next action hint, metadata) and specifies the action 'check what state a transaction is in.' This distinguishes it from other sibling tools like agirails_accept_quote or agirails_cancel.

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 says 'Use to check what state a transaction is in,' which gives clear usage context. It does not mention when not to use or list alternatives, but the read-only nature is evident from annotations and sibling names, making the guidance adequate.

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 indicate non-read-only (false) and non-destructive (false). Description says it returns a snippet (read-like) but also mentions 'register agent on-chain,' which could imply mutation. However, the tool itself only generates code (non-destructive), and the description does not contradict annotations. It adds context about the generated code's role but could clarify that the tool does not perform the registration itself.

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, zero waste. Essential information is front-loaded. Every sentence serves a clear purpose.

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 (returns a snippet for initialization), the description covers what it returns, why to use it, and the required action. No output schema exists, but the description adequately describes the return value. It is complete for the tool's role.

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 has 2 parameters with 50% description coverage (name described, network only enum). Description mentions 'agent name' but does not add meaning beyond the schema. The network parameter's purpose (mainnet vs testnet) is not explained. Overall, description adds minimal value to parameter understanding.

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?

Description clearly states the tool returns a TypeScript snippet for setting up AIP-13 keystore and registering an agent on-chain. It uses specific verbs ('returns', 'set up', 'register') and identifies the resource (init code). The purpose is distinct from sibling tools like agirails_find_agents or agirails_pay.

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?

Description says 'Run the generated code first to get your agent address and start transacting,' implying this is a prerequisite for other actions. However, it does not explicitly mention when NOT to use it or list alternatives. The context is clear but lacks explicit exclusions.

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 the tool as read-only and idempotent. The description adds filter options but does not disclose behavior beyond that, such as pagination, rate limits, or authentication needs. The mention of 'TypeScript snippet' introduces ambiguity rather than clarity.

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 sentence, no wasted words. However, it could be restructured to more clearly separate the action from the filter details, and the 'TypeScript snippet' phrase is an odd inclusion that reduces clarity.

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 four optional parameters, no output schema, and many sibling tools, the description fails to explain the output format, pagination, or the role of the 'network' parameter. The cryptic 'TypeScript snippet' remark adds confusion. Significant gaps remain.

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 coverage, the description must compensate. It explains the 'state' and 'role' parameters and their enum values but ignores 'limit' and 'network'. This partial coverage limits the description's value in helping agents set parameters correctly.

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 lists transactions with optional filters, specifying valid state and role values. However, it does not differentiate from the sibling tool agirails_get_transaction, and the phrase 'Returns a TypeScript snippet' is ambiguous about the actual output format.

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 alternatives like agirails_get_transaction or other list tools. The description omits any context about use cases or when not to use this 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?

The description does not clarify whether the tool performs the payment or only generates code, leaving a critical behavioral gap. Annotations (readOnlyHint=false, destructiveHint=false) do not resolve this ambiguity, and no side effects, permissions, or state changes are 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 consists of two sentences, front-loading the core action and adding a usage note. Every sentence serves a purpose, though the second sentence is terse. No unnecessary 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 has 4 parameters (2 required, no output schema), but the description does not explain the return format (the snippet contents), the 'service' parameter, or behavior on different networks. It lacks prerequisites, error conditions, or expected outcomes, leaving significant gaps despite moderate complexity.

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 description adds value by explaining the auto-selection logic for the 'target' parameter, but only 50% of parameters have schema descriptions (target, amount). The 'service' and 'network' parameters lack any explanation in the description or schema, despite 'network' having an enum and default. The description could better map parameter roles.

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 it returns a TypeScript snippet for smart pay, and distinguishes from sibling tools by highlighting automatic selection between ACTP escrow and x402 instant payment. The verb 'returns' is specific, though the resource 'TypeScript snippet' could be more direct.

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 a clear usage context: 'Use for direct payments without negotiation.' However, it does not explicitly state when not to use this tool or mention alternatives among the many sibling tools (e.g., agirails_request_service for negotiation-based payments).

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?

Description claims the tool returns a snippet (implying read-only operation), but readOnlyHint=false suggests potential side effects. This contradiction misleads the agent about the tool's true 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?

Two sentences, front-loaded with the core action. No unnecessary words, though an explicit statement of output type would improve structure.

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?

Provides context about the outcome of running the generated code, but lacks parameter explanations, error scenarios, or any detail about the snippet's behavior. Particularly incomplete given the annotation contradiction.

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?

Both parameters are documented in the schema, but with 0% schema description coverage, the description should explain their purpose. It only mentions AGIRAILS.md as the default configPath but doesn't clarify configPath or network 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?

Clearly states the tool returns a TypeScript snippet for publishing AGIRAILS.md to IPFS and registering on-chain. Distinguishes from sibling tools like agirails_find_agents or agirails_get_balance which serve different purposes.

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?

Implicitly indicates usage for making an agent publicly discoverable, but lacks explicit guidance on when to use versus alternatives or prerequisites. No mention of when not to use.

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?

Discloses the state change (INITIATED) and that funds are not locked, adding context beyond readOnlyHint and destructiveHint. 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?

Two sentences, no unnecessary words, front-loaded with the main purpose. Highly efficient.

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?

Explains return type and state, but could clarify whether the tool executes the request or just returns a snippet. Lacks information on error handling, side effects, or how to use the snippet. Given complexity, more detail would help.

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 60%, and description adds some value for the service parameter (mentions SDK usage). However, agentSlug lacks description in both schema and description, and no additional param details are provided.

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?

Description clearly states it returns a TypeScript snippet to request a service, initiating an ACTP transaction. Differentiates from siblings like agirails_accept_quote and agirails_cancel.

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?

Explicitly mentions that funds are not locked yet and advises to use agirails_accept_quote after receiving a price. Provides clear next-step guidance, though could be more explicit about when not to use.

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 idempotentHint. The description adds that it is the 'fastest way to get accurate AGIRAILS information,' but this is minimal additional behavioral context beyond confirming a read-only, idempotent 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?

Two sentences, no redundancy. The first sentence states the action and resource, and the second provides a concise list of use cases, making it efficient and 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?

Given the tool has 3 parameters (1 required) and no output schema, the description adequately covers search scope and hints at speed, but lacks details on pagination or result format. Annotations cover safety, so completeness is good but not excellent.

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 33% (only 'query' has a description). The tool description adds guidance to use natural language for the query parameter, compensating partially for the missing schema descriptions, but leaves 'limit' and 'type' without additional semantic context.

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 it searches AGIRAILS documentation and lists specific topics (e.g., agent payments, escrow, dispute resolution), making the purpose highly specific and distinguishing it from sibling tools that perform other actions.

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 advises using this tool for questions about a comprehensive list of topics, providing clear guidance on when to use it, though it does not explicitly exclude other scenarios or name alternatives.

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 that the tool updates provider reputation beyond annotations. It clarifies the tool returns a snippet rather than directly settling. Annotations indicate it mutates state, but the description suggests the mutation occurs when the snippet is run.

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 concise sentences: first defines purpose, second gives usage condition and side effect. No redundant information.

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 core purpose, usage condition, and side effect. However, it does not explain the output snippet format or that the tool itself does not execute the settlement directly, which could be important for an agent.

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 description does not mention any parameters or provide guidance on them. With only 50% schema coverage (network parameter lacks description), the description should compensate but fails to add value for parameter usage.

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 returns a snippet to release escrowed USDC, completing the DELIVERED→SETTLED transition. This distinguishes it from sibling tools like agirails_deliver and agirails_dispute.

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 says to generate the code when satisfied with the delivery, providing clear context for when to use it. However, it does not explicitly name alternatives like agirails_dispute for when unsatisfied.

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 indicate a write operation (readOnlyHint false) and no destructiveness, but the description adds confusion by stating it 'Returns a TypeScript snippet' without explaining the side effect or actual submission behavior. Important details like authentication, rate limits, or the snippet's role are omitted.

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 sentence that front-loads the main action and state transition. However, the phrase 'Returns a TypeScript snippet' may be unnecessary or misleading, slightly reducing efficiency.

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?

Without an output schema, the description should clarify the return value and side effects, but it only vaguely mentions a snippet. It fails to explain the purpose of estimatedDelivery and network, or how the snippet is used, leaving significant gaps for a tool with 5 parameters.

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 schema covers 60% of parameters with descriptions; the description reinforces price and deliverables but adds no new detail for estimatedDelivery or network, which lack schema descriptions. It partially compensates but does not fully bridge the gap.

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 that the tool submits a price quote and transitions a service from INITIATED to QUOTED, which aligns with the name. However, the mention of 'Returns a TypeScript snippet' introduces ambiguity about whether the tool actually performs the submission or only generates code, slightly reducing clarity.

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 the tool is for providers responding to a service request, but it does not explicitly distinguish it from sibling tools like agirails_accept_quote (for buyers) or provide 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?

Annotations (readOnlyHint, idempotentHint) already indicate safe, idempotent operation. The description adds that the tool generates code that fetches DID, endpoint, and reputation, which is useful behavioral context. No contradictions.

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 the main action, no unnecessary words. Every sentence adds value.

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 2 params, no output schema, and simple functionality, the description covers purpose, required param, usage context, and behavioral effect. Could mention output format or what happens if network isn't specified, but overall adequate.

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 covers 50% of parameters with descriptions. Description adds meaning for agentSlug (used for DID lookup) but provides no additional info for network (only enum/default in schema). Partially compensates for the gap.

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 it returns a TypeScript snippet for on-chain verification via AgentRegistry, specifying the verb (returns) and resource (code snippet). It distinguishes from sibling tools like agirails_find_agents and agirails_get_agent_card by focusing on verification.

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?

Provides clear context: 'Use before high-value transactions' and explicitly requires agentSlug for DID lookup. Does not mention alternatives or when not to use, but the guidance is sufficient for typical use cases.

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