trading-mcp

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states return values (exact USDC price, payment flow, latency), the payment mechanism (EIP-3009 sign → retry with X-Payment header), that it does NOT execute, and that it is free. This goes well beyond minimal transparency, though it omits potential details like authentication requirements or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is three sentences total, with the main purpose front-loaded in the first sentence. Every sentence adds value (quote details, non-execution clarification, and cost/free note). No fluff or repetition.

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 one-parameter tool with no output schema, the description covers essential context: what it returns, how payment works, that it does not execute, and that it's free. It is slightly incomplete in not describing the structure of the returned quote or potential errors, but it is largely sufficient for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'endpoint' has 100% schema description coverage, so the schema already fully documents it. The tool description adds no additional semantics about the parameter, resulting in a baseline score of 3.

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's purpose: 'Get payment instructions + live quote for any paid AI Rook endpoint.' It uses a specific verb ('Get') and resource ('payment instructions + live quote'), and explicitly differentiates itself from sibling tools by stating it does NOT execute the endpoint, only plans payment.

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 explicit usage guidance: 'use this to plan, then pay via x402 at the endpoint URL.' It also clarifies what it does not do (does not execute). It does not name alternative tools but the context is clear enough for an agent to decide when to invoke it.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It thoroughly states that the tool is non-invasive ('WITHOUT touching the chain') and discloses what it delivers: exact contract calls, calldata, gas estimates, money split, state transitions, and reject/refund alternates. The mention of 'Verified against live job 39' provides additional trust context. It does not cover error handling or output format, but for a dry-run tool the disclosed behavior is sufficient.

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 information-dense. It uses one efficient sentence with a colon-separated list of outputs, followed by two short imperative clauses ('Use before creating any escrow job. Free.'). Every word earns its place, with no filler or redundancy.

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 lacking an output schema and annotations, the description provides a comprehensive overview of the tool's outputs and context. It lists the specific data returned (contract calls, calldata, gas estimates, money split, state transitions, reject/refund alternates) and gives usage context. It could be slightly more explicit about the return structure or error behavior, but for a dry-run tool this is well-rounded.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and each parameter (hours, amount, provider) has a concise, meaningful description. The tool description itself does not add parameter-specific details, but the schema already provides examples and defaults (e.g., '250000 = $0.25'). This meets the baseline of 3, as the description isn't required to compensate.

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's function: 'Preview a full ERC-8183 escrow job lifecycle on Base WITHOUT touching the chain.' It specifies the exact resource (escrow job lifecycle) and the verb 'preview,' which distinguishes it from sibling tools like get_escrow_job or the other preview_* tools. The detail about 'exact contract calls, calldata, gas estimates, money split' further clarifies its specific role.

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 explicit usage guidance: 'Use before creating any escrow job.' It also implies a key distinction from actual execution by emphasizing 'WITHOUT touching the chain,' which signals it is a safe, pre-execution step. However, it does not explicitly mention when not to use it or name alternative tools, so it misses the full when/when-not 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?

With no annotations, the description carries the full burden and does disclose that this is a read operation (free, on-chain read) and lists the returned fields. However, it does not mention behavior for non-existent job IDs, potential errors, or any prerequisites beyond the job being completed/rejected, leaving some behavioral gaps.

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 compact two-sentence structure that leads with the primary verb and resource, then lists return fields and the tool's purpose. Every clause adds useful information without redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool with one parameter and no output schema, the description covers the tool's purpose, input scope, output contents, and cost. It does not explain edge cases (e.g., missing attestation), but given the simplicity, the description is sufficiently complete for an agent to select and invoke the tool 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 coverage is 100% and the single parameter job_id is described in the schema. The description adds meaningful context beyond the schema by restricting the job state to 'completed/rejected' and clarifying that the job is an ERC-8183 job, which enhances understanding of the parameter's domain.

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 uses a specific verb ('Read') and clearly identifies the resource ('on-chain attestation record') plus the relevant scope ('for a completed/rejected ERC-8183 job'). It also explicitly differentiates from siblings by stating it provides proof that the RookAttestationHook fired, which is distinct from get_escrow_job or sign_receipt.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: for completed/rejected ERC-8183 jobs, and explains the intended purpose (proof of hook execution). It does not explicitly name alternative tools or state exclusions, so it stops short of full alternative 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?

With no annotations, the description carries the burden of disclosing safety and behavior. 'Read' explicitly indicates a non-mutating operation. It also mentions 'Free' (pricing/cost behavior) and lists the output fields, providing useful context about what the tool returns. It doesn't discuss rate limits or error handling, but for a simple read tool this is reasonable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences: the first defines the core purpose and return fields, the second gives a helpful real-world example, and the third notes the tool is free. Every sentence adds value; no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, no output schema), and the description adequately covers what the tool does and what it returns by listing the state fields. It also includes a known example (Job 39). Missing details like error behavior or exact response format are not critical for this simple tool, making it fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the only parameter job_id is already described as 'Job ID (integer)'. The description adds a concrete example ('Job 39 is our verified live completion') which gives additional context on how job IDs map to real jobs, but doesn't introduce new semantic details beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads on-chain escrow job state by ID, and enumerates the specific fields returned (status, client, provider, budget, deliverable hash). This specific verb+resource clearly distinguishes it from sibling tools like get_quote or get_attestation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: use this tool whenever you need the state of an escrow job by ID. It says 'any' job, giving broad applicability. It doesn't explicitly name alternatives to avoid, but the read-only purpose is clear, and there are no exclusions stated.

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

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

With no annotations, the description carries the transparency burden. It discloses that latency is 'REAL measured latency (from production paid calls)' and that the tool is 'Free', implying no paid endpoint execution. However, it does not mention authentication, rate limits, or response format, leaving some behavioral gaps.

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 punchy sentences front-load the key information: exact price, input schema, real latency, and cost-free usage. Every word adds value, with no redundancy.

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 1-parameter tool with no output schema, the description is complete. It names the three key returned items (price, input schema, latency), explains the use case, and conveys the no-cost aspect, giving an agent enough to decide and use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single endpoint parameter, which already includes an example. The tool description adds only that it works for 'any AI Rook endpoint', providing no new semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs and resources: 'Get exact price, input schema, and REAL measured latency' for 'any AI Rook endpoint' before paying. This clearly distinguishes it from siblings like call_paid_endpoint by positioning it as the pre-payment quote tool.

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 explicitly states when to use the tool: 'before paying' and 'quote first, pay second'. The 'Free' note reinforces it as a low-risk pre-check, but it does not explicitly name alternatives like call_paid_endpoint or state when not to use it beyond the implicit 'when ready to pay'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds valuable context: the tool is free, lists 52 endpoints, and covers specific categories (trading intelligence, AI inference, etc.). The verb 'List' implies a read-only operation, so no side effects are expected, though it does not explicitly state the absence of side effects or describe the return format in 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?

The description is two sentences, front-loaded with the core function ('List the full AI Rook endpoint catalog with prices'). The parenthetical enumeration of endpoint categories is efficient and adds useful detail without bloat. 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?

For a zero-parameter listing tool with no output schema, the description is nearly complete: it states what the tool returns (the catalog with prices), the cost (free), and when to use it (start here). It could optionally mention whether the result is paginated or the exact structure of the catalog, but given the simplicity of the tool, the description is 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?

The tool has zero parameters, so the description does not need to explain parameter meanings. The baseline of 4 applies because the schema is trivially complete (empty object) and there is nothing to add.

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 ('List') and the resource ('full AI Rook endpoint catalog with prices'), including the endpoint count and categories. It distinguishes itself from sibling tools like call_paid_endpoint and get_quote, which perform specific actions rather than listing the catalog.

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 instructs users to 'START HERE before calling any paid endpoint', providing strong when-to-use guidance. It also mentions the tool is free, reinforcing it as a safe, initial discovery step. This is sufficient context to guide tool selection among the siblings.

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?

With no annotations provided, the description carries full burden. It discloses the free nature, the fact that data is real, and that specific fields are redacted. It does not mention authentication or rate limits, but for a simple preview tool this is adequate and non-contradictory.

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 that are front-loaded and free of fluff. Every clause adds value: free trial, endpoint cost, data included, what's redacted, and the intended use case.

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 zero parameters, no output schema, and no annotations, the description is remarkably complete. It tells the agent exactly what the tool offers, why to use it, and the limitations, making it suitable for selection without needing further 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?

The tool has zero parameters and the schema is empty, so the baseline is 4. The description adds no param info, but none is needed.

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 is a free preview of the paid /api/market-pulse endpoint, specifying the exact data included (BTC price, engine status) and what is redacted (CVD/OI/whale fields). This distinguishes it from sibling preview tools like preview_order_flow and preview_trade_idea.

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 states when to use: 'Use to evaluate data quality before paying.' It also notes 'No payment required,' implying this is a trial before using the paid call_paid_endpoint. This gives clear context 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?

Since no annotations are provided, the description carries the full disclosure burden. It openly states that this is a free taste, that the paid endpoint costs $0.25, and that CVD/session levels are redacted, giving a realistic expectation of limitations. It does not mention rate limits or output specifics, but it is sufficiently transparent for a preview tool.

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, information-dense sentence that covers the free nature, the paid endpoint and cost, the included data, the redactions, and the evaluation purpose. It is concise and front-loaded, with no wasted words. The minor oddity of 'gear' (possibly a typo for 'data') does not impair understanding.

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 zero-parameter, no-output-schema preview tool, the description provides sufficient context: it identifies the source endpoint, what data is included and redacted, and why an agent would use it. It lacks explicit output format or usage limits, but these are not critical for invocation, making the description adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, making the input schema empty. The description appropriately avoids parameter details since none exist, and no additional parameter semantics are needed. This aligns with the baseline of 4 for 0-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 that this tool provides a free preview of the paid /api/order-flow endpoint, specifying what is included (real price and volume) and what is redacted (CVD/session levels). It distinguishes itself from other preview tools and the paid call_paid_endpoint by naming the specific underlying endpoint and its cost.

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 phrase 'Evaluate before paying' explicitly conveys the primary use case: to assess the paid API before committing a fee. It implies that the full version is available for payment, though it could more explicitly name an alternative like call_paid_endpoint for full data. The intent is clear, but the exclusion is not explicit.

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?

With no annotations provided, the description carries the burden of behavioral disclosure. It transparently states that this is free and that certain fields (entry/stop/target) are redacted, which are key behavioral traits. It does not cover rate limits or authentication, but for a simple preview tool, the disclosed limitations are sufficient.

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 and front-loaded with the key selling point 'FREE taste'. It packs the essential information (endpoint, what is included, what is redacted, and the purpose) into a compact two-sentence structure with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description provides enough context to understand the tool's purpose and limitations. It mentions the cost of the paid alternative and the redaction behavior, which covers the core decision-making needs. It could have explicitly mentioned using call_paid_endpoint for the full version, but that is inferable from the 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?

The tool has zero parameters, so the description does not need to explain parameter meanings. The schema is empty and the description does not claim any inputs, which is consistent and non-confusing. The baseline of 4 for no-parameter tools 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 identifies the tool as a free preview of the paid /api/trade-idea endpoint and specifies exactly what is returned: strategy name and direction, with entry/stop/target redacted. This distinguishes it from sibling preview tools by naming the underlying endpoint and detailing its limited scope.

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 phrase 'Evaluate before paying' explicitly signals the tool's purpose as a pre-purchase evaluation aid, implying it should be used before calling the paid endpoint. It does not explicitly name alternatives like call_paid_endpoint, but the context of being a 'FREE taste' makes the usage context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the verification process ('Server verifies the on-chain Transfer event'), the signing method ('AI Rook server wallet (EIP-191)'), and verifiability ('ecrecover-verifiable offline'), which are valuable. It does not cover error cases or auth requirements, but does well for the scope.

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 composed of three efficient sentences: purpose, process, and use case, plus 'Free.' as a final note. There is no fluff, and the primary purpose is front-loaded in the first sentence.

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 (one parameter, no annotations, no output schema), the description covers the key aspects: what it does, how it works, and when to use it. The output format is hinted at by 'ecrecover-verifiable offline', but not fully specified, which is a minor gap.

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 already fully describes the parameter (tx_hash format), giving a baseline of 3. The description adds meaning by specifying the transaction type ('any USDC payment tx') and requiring a Transfer event, which goes beyond the schema's generic 'transaction hash on Base'.

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's function with a specific verb ('Generate') and resource ('cryptographically signed proof-of-spend receipt') scoped to USDC payment tx on Base. This distinguishes it from sibling tools like get_attestation or call_paid_endpoint, 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?

The description provides a clear use case ('For agent operator audit trails') and implies the tool is for generating receipts after USDC payments. However, it does not explicitly state when not to use it or name alternative tools, so it lacks full exclusions.

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