TRDEFI Liquidity

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

With no annotations, the description carries the full burden, but it only says 'payload' without specifying the format (JSON/SVG) or any behaviors like failure modes, caching, or rate limits. It does not disclose what the endpoint returns beyond being a badge payload, which is a significant gap for an agent.

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 focused sentence followed by a metric list. It is front-loaded with the purpose and contains no superfluous wording. The list is necessary because it enumerates allowed values.

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 param, no output schema), but the description omits crucial details about the actual payload structure required by shields.io (e.g., JSON schema with label, message, color). An agent would not know how to interpret or consume the response. Given no output schema, this is a notable 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 provides an enum for the single parameter, so the parameter is self-explanatory. The description adds the context that these are 'catalogue metrics' and lists them, which is redundant with the enum but adds minor semantic framing. Since schema coverage is 0%, the description provides some value but not much beyond restating the enum.

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 produces a shields.io endpoint payload for catalogue metrics, intended for README badges. It distinguishes itself from sibling data tools (trdefi_stats, trdefi_positions, etc.) by its purpose (display vs. raw data retrieval), though it doesn't explicitly name the alternatives.

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

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

Usage context is implied: 'so a README can show live figures' suggests when to use it (for badges), but there is no explicit guidance on when not to use it or when to prefer a sibling tool. The distinction from data-returning tools is implicit rather than 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 behavioral disclosure burden. It communicates that the data is dynamic ('where liquidity is live right now') and frames the tool as a lookup source, implying a read-only, current-state query. It is slightly light on details like data freshness or error behavior, but adequate for a zero-parameter reference 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 two sentences with no filler. It front-loads what the tool returns and then states the recommended usage, making it immediately scannable for an agent.

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 tool with no output schema, the description covers the essential return content: networks, settlement engine addresses, and tokens. It does not specify the exact response shape, but an agent has enough context to invoke it correctly.

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

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

The tool has zero parameters and the schema documents this completely, so there is no need for the description to explain arguments. The baseline of 4 applies because no parameter semantics are required.

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 what the tool provides: the currently live liquidity networks, each network's settlement engine address, and the usable tokens. It also distinguishes itself from siblings by framing itself as the authoritative source for chain and token identifiers rather than positions, quotes, or stats.

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 'Use this instead of hardcoding chain or token identifiers' gives explicit, actionable guidance about when to call this tool. It does not mention exclusions or compare directly to sibling tools, but the intended context 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 burden of behavioral disclosure. It states what is returned ('one position in full') but does not mention whether the operation is read-only, what happens if the hash is not found, or any side effects. This is minimal behavioral transparency for an unannotated 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, front-loaded sentence with zero wasted words. It immediately states the resource and the key identifier. It is appropriately sized for the tool's simplicity.

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 lookup tool with one fully documented parameter, the description is minimally viable. However, with no output schema and no annotations, the agent is left without details on the return structure or error behavior. 'In full' is vague and does not specify what fields are included.

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 schema already documents the hash parameter fully. The description adds the '32-byte' context, which is technically redundant with the schema's '64 hex characters' but reinforces the format. No additional semantic value beyond the schema is 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?

The description clearly identifies the resource (a single position) and the identifier (32-byte strategy hash), and it implicitly distinguishes itself from the sibling trdefi_positions by focusing on one position in full. It lacks an explicit verb like 'get' or 'retrieve', but the intent is unambiguous.

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

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

No guidance is given on when to use this tool versus alternatives such as trdefi_positions. The description only implies that a hash is required, but does not explain how to obtain one or when a full detail lookup is appropriate. There are no exclusions or alternative routing.

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. It discloses that the data is 'live', 'non-custodial', and 'free, no key, no custody', which conveys safety, cost, and authentication behavior beyond the schema. It also outlines the row contents. It does not mention result ordering or response envelope details, but the most decision-relevant behaviors are covered.

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

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

Four sentences with each earning its place: value proposition, row contents, use cases, and safety/auth. The core purpose is front-loaded and there is no filler or repetition of schema details.

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 compensates by enumerating the row fields (strategy hash, network, pair, tokens, settled volume) and giving usage scenarios. It does not specify the exact response container, ordering, or default network behavior, but for a simple filterable list tool these gaps are minor.

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 all three parameters are already well documented. The description adds only 'Filter by network and by pair,' which mirrors the schema rather than adding new meaning. Per the calibration rule, this is a baseline 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?

The description clearly identifies the resource (live USDC/USDT maker positions), what they are (non-custodial stablecoin liquidity an agent can trade against), and what each row contains. It implicitly differentiates itself from siblings like trdefi_position_detail by presenting this as the multi-row survey/list tool rather than a single-position detail view.

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

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

Gives explicit when-to-use context: 'Use this before a stablecoin swap to find a real on-chain counterparty, or to survey where stablecoin liquidity sits.' It also mentions the available filters, but it does not explicitly name alternative sibling tools or state when not to use it, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden. It discloses that the operation is on-chain, involves no custody/signing/moving, and runs at the current block. Critically, it discloses a significant behavioral trait: a maker may gate the position on an access licence token, and roughly four in five such positions will return a clear reason instead of a price, explicitly framing that as a strategy property rather than an error. This is exceptional transparency beyond basic read-only.

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

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

Three sentences total: the first front-loads the core purpose and read-only guarantee; the second gives a concrete use case; the third adds an important behavioral caveat. No wasted words, every sentence earns its place. The structure is clear and 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?

Given the tool's moderate complexity (4 params, no output schema), the description covers purpose, usage, and critical behavioral notes. It does not describe the return format or exact response structure, which would be helpful since there is no output schema. However, the description gives enough to understand what to expect (output amount, possible reason instead of price). The missing response shape is a minor gap, so a 4 is appropriate.

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 75%, with descriptions for hash, chain, amount, and direction. The description itself adds no additional parameter details beyond what the schema already provides. It does not mention amount units or direction semantics, but the schema covers those. Baseline of 3 is appropriate since the description does not compensate for the 25% gap (chain default) but the schema already has reasonable descriptions.

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 verb 'Price' a stablecoin swap against one position, with on-chain and current block qualifiers. It distinguishes from siblings by focusing on quoting a single position, whereas siblings handle positions, stats, chains, badges. The 'no custody, nothing signed, nothing moved' phrase reinforces its read-only nature.

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 instructs to use this tool 'to check USDC/USDT liquidity and get the output amount before preparing a swap.' This provides a clear use case. It does not name alternative tools or exclusions, but given sibling names and context, the intended usage is unambiguous. The note about access licensing provides important context on when a price might not be returned.

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 behavioral transparency burden. It discloses that this is a read-style aggregation tool, requires no key, and spells out the exact statistics returned. It does not mention rate limits or response format, but these are minor for a zero-parameter stats endpoint.

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 one dense, front-loaded sentence that lists what the tool returns without filler. Every phrase adds information, including the closing 'Free, no key' note, so nothing could be trimmed without losing 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?

For a zero-parameter aggregate stats tool with no annotations and no output schema, the description covers the purpose, the metrics available, and the access requirement. It does not specify the response envelope or formatting, but an agent has enough to decide whether to invoke it.

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 an empty object with 100% coverage, so there are no parameter details needing clarification. Per the zero-parameter baseline, the score is 4.

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 starts with the specific verb 'Aggregate statistics for the live TRDEFI non-custodial stablecoin liquidity catalogue' and enumerates concrete metrics. This clearly differentiates it from siblings like trdefi_positions or trdefi_position_detail by being catalogue-wide and aggregate rather than item-level.

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 establishes clear context: use it for aggregate statistics about the live catalogue, and it explicitly notes 'Free, no key' so an agent knows access requires no authentication. It does not explicitly name alternatives or state when not to use this tool, but the context strongly implies when it is appropriate.

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