cleartrace

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

With no annotations, the description carries the behavioral burden and does it well: it warns that volume columns are of two kinds, that overlays must not be summed with partition columns, and that a suffix figure larger than the total is expected behavior. It does not explicitly state read-only behavior or rate limits, but the substantive data behavior is 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 purpose statement is front-loaded, and the critical column-semantics and freshness warnings are essential for correct use. The description is somewhat long and contains a mild editorial phrase, but every substantive sentence contributes to preventing misinterpretation.

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 is largely complete: it names the key return columns and explains their relationships, and the schema covers all three optional parameters. Since there is no output schema, it would benefit from explicit statements about row grouping or response envelope, but the core invocation and interpretation guidance 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?

Schema description coverage is 100%, so the baseline is 3. The input schema already documents chain, limit, and project with defaults, fallback behavior, clamping, and accepted values; the description adds no parameter-level meaning beyond that.

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 exactly what the tool does: it identifies which frontend, router, or interface originated on-chain DEX volume, aggregated per contract per chain. It is clear and distinguishes the tool from generic contract lookups, but it does not explicitly differentiate itself from the closely named sibling contract_attribution.

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

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

It gives strong usage context: use this tool when you need to name the venue behind anonymous contract volume, and it explains how to interpret/display results (weekly, never as today's). It does not explicitly state when to choose this tool over alternatives, but the context is clear and no exclusions are given.

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, and it does so thoroughly. It discloses that unlabeled addresses return a null label, that empty results can occur for well-known contracts, and that guessing an operator from volume or deployer is unreliable. This goes well beyond restating the tool's purpose and protects the agent from misinterpreting results.

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

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

The description is front-loaded with a clear definition, and the following paragraphs provide valuable interpretive guidance rather than filler. It is slightly longer than strictly necessary, but each warning earns its place by preventing incorrect conclusions from empty or null results.

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 two-parameter tool with no output schema, the description covers invocation scope, the effect of the optional chain parameter, and the important semantic states of the result (null label, empty result). An agent has enough context to select the tool and interpret its output 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 100%, and both parameters already have meaningful descriptions in the schema. The description adds minor context about the address being a single contract or wallet, but it does not substantially improve on the schema's parameter 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 opens with a precise, specific definition: it returns what ClearTrace knows about a single contract or wallet address, including per-chain volume split across four attribution vectors and any resolved label. It also explicitly differentiates itself from aggregate views by naming anonymous routers and proxies as 'the differentiated question this answers.'

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 clear when-to-use guidance ('Most useful on the ANONYMOUS routers and proxies') and explains a key caveat: known named protocol contracts may return nothing, so an empty result is not evidence of obscurity. It does not explicitly name a sibling tool to use instead, but the conditions for use are clearly implied.

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

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

With no annotations to rely on, the description carries the full behavioral burden. It discloses that the score captures slippage only, that high scores can coexist with high revert rates, and that execution quality varies across chains. It does not detail output shape or data freshness, but the core behavioral caveats are clearly surfaced.

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 well structured and front-loaded: the core definition comes first, followed by essential caveats and chain guidance. It is slightly repetitive with the schema's warning about not describing the blend as one chain's result, but every sentence earns its place and the warnings are important.

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 two optional parameters, no required inputs, and fully documented schema fields, the description is complete. It explains what is measured, how scores are expressed, what is deliberately excluded, when to use the sibling revert_rates tool, and how the chain parameter affects the result. No critical invocation detail is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explicitly framing the chain parameter as a choice between 'single-chain ranking' and 'blended cross-chain rollup,' with the rationale that execution quality is not uniform across chains. The limit parameter is already fully documented in the schema, including clamping behavior and the context-window rationale.

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 and resource: 'Rank DEXs and aggregators by realized execution quality: median slippage against a 1-minute VWAP baseline.' It defines the score scale and differentiates the metric from revert rates and MEV exposure, making it distinct from the sibling revert_rates 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?

The description explicitly warns this is not an overall best-execution ranking, states that revert rates and MEV are separate metrics, and directs the caller to revert_rates for that information. It also gives chain-mode guidance: pass a chain for single-chain ranking or 'all' for the blended rollup, with a clear caveat not to misrepresent the blend as a single chain's result.

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 transparency burden and does so fully: it discloses upstream credit costs for deep mode, the fallback behavior for unrecognized chains, and the approximate nature of the price estimate. It also explains that fee amounts are exact raw integers, setting accurate expectations about the response content.

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 dense but every sentence adds operational value: scope, evidence types, confidence caveats, cost guidance, and caveats about numeric precision. It is well-structured with no filler or redundant 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?

Even without an output schema, the description enumerates what the result contains: frontend/router attribution, evidence, pools, fee recipients, sandwich status, price context when requested, and fee amount semantics. It also covers input behavior, cost implications, and precision limits, making the tool fully understandable 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?

All four parameters are described beyond the schema: tx_hash is tied to a specific chain and wrong-chain hashes return nothing; chain lists accepted values and its fallback behavior; deep explains when to enable it; price explains what it adds. The descriptions add decision-relevant meaning rather than re-stating field names.

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 ('Classify') and a concrete resource scope: a single transaction's routing origin, evidence, pools touched, fee recipients, and sandwich status. It also clarifies that this is the single-transaction explanation tool versus the broader attribution engine, making its purpose distinct.

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 direction: 'deep=true costs more upstream credits' and should be left off unless the shallow pass came back unattributed; 'price=true' is required for estimated volume; the chain default fallback behavior is flagged; and the warning not to quote the volume as a settlement figure is clear. This tells the agent exactly when and how to invoke the 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?

With no annotations provided, the description carries the full burden, and it does exceptionally well: it discloses that L2 values exclude L1 data availability fees, explains that costs built from this are lower bounds, and warns against misleading cross-chain comparisons. This is exactly the kind of behavioral nuance an agent needs.

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 core purpose is front-loaded in one sentence, followed by a necessary caveat about L2 pricing semantics. The caveat is somewhat long but earns its place because it materially changes how the result should be interpreted. No wasted filler, though it could be tightened slightly.

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 what the tool returns, its source, and its most important interpretive limitation. It does not enumerate supported chains or specify return units/format, but with zero parameters and a simple read-like use case, these are minor gaps. The caveat makes the description sufficiently complete for correct use.

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 no parameters and the schema is complete, so there is no parameter documentation burden. The description adds no parameter-specific meaning because none is needed; the baseline of 4 for zero-parameter tools applies.

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

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

The description states a specific verb-resource pair ('Current gas price on each supported chain') and names the data source ('from RPC'). It clearly distinguishes this as a live gas-price lookup tool and is not confused with the sibling tools like attribution or execution_benchmarks.

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 signals it is for current gas prices and gives concrete guidance on how to interpret the value for L2s, warning that it is a lower-bound cost estimate. It does not explicitly name alternatives or when-not-to-use conditions, but the context is clear enough for an agent to select it appropriately.

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 fully carries the behavioral burden. It discloses that the key changes limits only, that no data is gated, that the key is returned once and cannot be shown again, and that the agent must ask the user for the email. This is exceptionally transparent for a side-effectful 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?

The purpose is front-loaded in one sentence, and the following caveats are dense but each earns its place: limit-only effect, no invented email, one-time key return. There is no fluff or repetition relative to 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 tells the agent what the tool does, what it does not do, how to obtain required input from the user, and how to handle the output. For a simple tool with no output schema, this is fully complete 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 100%, so the baseline is 3. The description adds no parameter-level meaning beyond the schema; even the email-safety guidance already appears in the schema's parameter description. The description does not compensate further, so a 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 first sentence states a specific verb ('Mint') and resource ('free API key') with a concrete effect ('multiplies this server's rate limits by 10x'). It is clearly distinct from sibling data-query tools like gas_prices or revert_rates, 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 gives clear context for when to use the tool: it raises rate-limit ceilings, not content access, and requires the user's email. It also tells the agent not to invent an email and to ask first. It does not explicitly name alternatives, but the sibling tools are unrelated enough that the boundary is 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, the description carries the full behavioral burden. It discloses the comparable_only default behavior, the structural near-zero rates for non-router venues, spam-sender inflation of headline rates, and the presence of execution_model and revert_comparable flags on each row. This goes well beyond a generic statement of what the tool returns.

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

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

The description is front-loaded with the core definition, then organized around the ranking caveat, the comparable_only guidance, and the user-rate caveat. It is dense but every sentence earns its place by conveying a real usage trap or output interpretation point.

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

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

There is no output schema, so the description appropriately names key return fields (user_revert_rate_pct, execution_model, revert_comparable) and tells the agent to quote them. It could be slightly more explicit about the full row shape, such as the presence of chain and project columns, but the essential semantics for correct use are covered.

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

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

Schema description coverage is 100%, so the baseline is 3 even without parameter details in the tool description. The schema already documents defaults, clamping, allowed chain values, and the meaning of comparable_only, so the description adds little new parameter-level meaning beyond reinforcing the same caveat.

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 first sentence states precisely what the tool measures: 'The share of a venue's routing transactions that fail on-chain, per chain.' It distinguishes the metric from slippage by saying 'reliability and price are different questions,' which separates it from a likely sibling like execution_benchmarks.

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 when-not guidance: 'DO NOT RANK ACROSS EXECUTION MODELS' and explains why ranking batch-auction/intent venues by revert rate is meaningless. It also tells the agent to keep comparable_only as default, to read user_revert_rate_pct when present, and to quote the row-level fields, leaving little room for misinterpretation.

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