TRDEFI Liquidity

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. With no output schema, the description adds real value by disclosing the response shape (a shields.io endpoint payload) — information an agent could not get from structured fields.

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 short sentences, front-loaded with the output format and purpose, with no filler. The metric enumeration is slightly redundant against the schema enum but is compact and readable.

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 single-parameter, read-only tool with no output schema, the description covers the essential context: what is returned (badge payload), why (live README figures), and the selectable metrics. Missing only per-metric semantics and sibling routing, which keeps it out of 5 territory.

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 lists the metric values, but that list simply mirrors the enum already in the schema and gives no meaning for each metric (e.g. what volume30 counts or what period 'makers'/'pairs' represent), nor does it mention the volume30 default.

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

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

The description names the concrete output ('a shields.io endpoint payload for the catalogue metrics') and its consumer (a README badge), which is specific enough to distinguish it from siblings like trdefi_stats or trdefi_chains. It is clear but never explicitly contrasts itself with those siblings.

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 is only implied via 'so a README can show live figures' — an agent can infer this is for embedding badge values, not for querying analytics data. There is no explicit when-to-use / when-not-to-use or pointer to trdefi_stats for raw figures instead of badge payloads.

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 readOnly, idempotent, openWorld, and non-destructive, so safety behavior is covered. The description adds only that the set is "live right now," implying the list is dynamic — a small but real addition. It says nothing about freshness, caching, or why the set might change, so it stays at baseline.

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 filler. The content of the response is front-loaded and the routing advice follows immediately, so an agent gets the essential facts in the first read.

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?

With no output schema and no parameters, the description carries the burden of describing the return payload, and it does name the two key fields (settlement engine address, buildable tokens). It stops short of describing the shape of those fields — identifiers versus objects, chain naming — which would help an agent chain this into trdefi_quote or trdefi_positions.

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 takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate; baseline 4 applies. The description usefully clarifies that the returned identifiers are the intended inputs to other calls, which is better than nothing.

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

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

The description names the resource (live networks) and enumerates what comes back: each network's settlement engine address and the tokens a position can be built from. That level of specificity lets an agent distinguish it from trdefi_quote, trdefi_positions, or trdefi_stats without opening a schema.

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?

"Use this instead of hardcoding chain or token identifiers" gives a clear condition for reaching for this tool rather than relying on built-in knowledge. It does not name sibling alternatives or state exclusions, but no sibling is a true substitute for this discovery call, so the guidance is 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 already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds 'in full', implying a complete detail record rather than a summary, but says nothing about what 'full' returns or any rate/error behavior.

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

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

One front-loaded sentence with zero filler; the resource and key are stated immediately and nothing is redundant.

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 one-param read tool this is nearly sufficient, but with no output schema the description should say more about what the returned 'full' position contains; the return shape is left entirely to inference.

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 param is documented with a 64-hex-char pattern, so the baseline is 3. The description's '32-byte' framing reinforces the pattern but adds no format or sourcing 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?

States a specific resource (one position) and its key (32-byte strategy hash), which distinguishes it from the plural sibling trdefi_positions. It is clear what the tool fetches, though it never names the sibling explicitly.

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 when-to-use statement, no alternatives, no prerequisites. An agent must infer from the name alone that trdefi_positions is the list-oriented alternative and that this is the single-record lookup.

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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new context: it is free, needs no API key, involves no custody, and the quote_eligible flag tells the agent whether /api/quote can simulate a row — useful operational detail 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?

Front-loaded with what the tool returns, then the fields, then the usage triggers and constraints. Four tight sentences with little waste, though "as positions an agent can actually trade against" is slightly promotional 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?

With no output schema, the description usefully enumerates the returned row fields and explains the quote_eligible flag, and covers access constraints (free, no key, no custody). Pagination/limit behavior is left to the schema, which documents it adequately.

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 pair, chain, limit and quote_ready in full; the baseline is 3. The description only restates that filtering is by network and pair and gestures at the quote_eligible flag, adding no syntax or semantics the schema lacks.

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 concrete resource — live non-custodial liquidity positions — and enumerates the row fields (strategy hash, network, pair, tokens, settled volume, quote_eligible), which makes the output concrete. It is clear what the tool returns, though it never explicitly names or contrasts the sibling tools (trdefi_position_detail, trdefi_quote) it sits beside.

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 explicit triggers: "Use this before a swap to find a real on-chain counterparty, or to survey where liquidity sits," plus the filtering affordances (network and pair). There is no when-not guidance and no named alternative for the narrower per-position or quote lookups.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: exact revert code 0x89c62b64 for gated strategies, why it happens (maker access-licence check requiring the 1inch Aqua access token for the caller), measured gating rates per network, and the authoritative list of 17 supported networks. That is far more than the annotations convey.

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?

Front-loaded with the core action and safety posture, then escalates into error handling and network coverage. It is long, but the gating and network-list content is operationally necessary; only 'That is a property of the strategy, not a bug' reads as 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?

With no output schema, the description should describe the return shape, and it only promises 'the output amount' without naming fields or units. Everything else an agent needs — chain coverage, defaults, gating behavior, ordering relative to swap preparation — is present.

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 instructs the agent to 'pass `from` with an address that holds the token', but no `from` property exists in the schema and additionalProperties is false, so following this instruction will fail validation — actively misleading. It also adds no meaning for `direction`, and only the network list enriches `chain` 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?

States a specific verb+resource (price a swap against a position) with explicit scope: on-chain, at current block, no custody, nothing signed. It also carves out behavior versus sibling read tools by framing it as the pre-swap pricing step. An agent can identify this as the quote path without opening any schema.

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 clear when-to-use context ('to check liquidity and get the output amount before preparing a swap') and clarifies a usage assumption ('any pair the position trades, not only stablecoins'). It does not name a sibling tool as an alternative 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description still adds value beyond them by disclosing that the data is 'live', that it spans the whole catalogue, and that access is 'Free, no key' — real operational context an agent cannot get from 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?

One front-loaded sentence that leads with the operation and scope, then itemizes the exact outputs. Nothing is redundant and nothing needs cutting; the trailing 'Free, no key.' is a short, useful addendum rather than 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?

With no output schema, the description must carry the return-value burden, and it does by enumerating counts, open maker positions, distinct makers, pairs, networks, settled volume windows and deepest pairs. Minor gaps remain (no units, no timezone/format hints for the volume windows), which keeps it just short of full 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly spends no words on phantom inputs.

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 gives a specific verb+resource ('Aggregate statistics for the live TRDEFI ... catalogue') and even enumerates the exact metrics returned. It is clear what the tool produces, but it never names or contrasts itself with any sibling (e.g. trdefi_positions, trdefi_chains) that superficially overlaps with the 'deepest pairs' data.

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

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

There is no explicit when-to-use or when-not-to-use statement, and no alternatives are mentioned. The natural reading — use this for a catalogue-wide overview rather than per-position lookups via trdefi_positions or trdefi_quote — is only implied by the aggregate framing.

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