yieldoracle

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

Without annotations, the description carries the burden of explaining behavior. It discloses the output categories (top pools, TVL, average APY) but does not cover potential edge cases, data freshness, or how 'best' is defined. It is adequate but not rich.

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 long, front-loads the core purpose, and every sentence adds value. There is no redundancy or fluff.

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 output schema and no annotations, the description explains the high-level return values (top pools, TVL, APY). It is reasonably complete for a simple yield explorer, though it could clarify the ordering criteria for 'best.'

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 input schema already documents all three parameters with descriptions and defaults, achieving 100% coverage. The description adds no additional parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool's function: retrieving the best yields for a specific chain, including top pools, total TVL, and average APY. It distinguishes itself from siblings like top_yields by emphasizing chain-specific 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?

The description provides a clear use case: 'Great for chain-specific farming strategies.' It implies when to use this tool but does not explicitly mention alternatives or exclusions, so it falls 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, the description carries the burden of explaining behavior. It does disclose the output categories (health, stats, status, tool list, pricing), but it never states that the operation is read-only or free of side effects. The name implies a safe health check, but the description could be more explicit.

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 entire description is a single, well-packed sentence. Every listed item (server health, data stats, API status, tool list, pricing) provides distinct useful information without superfluous wording. It is front-loaded and to the 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?

Given that there are no parameters, no annotations, and no output schema, the description covers the main response categories adequately in a compact way. It doesn't mention the actual data format or any error conditions, but for a simple health-check endpoint, the description is reasonably 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, so the description doesn't need to explain parameters. It adds context by describing what the response will contain, which is helpful in the absence of an output schema. The baseline for zero-parameter tools is 4, and the description meets 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 clearly lists the resources covered (server health, data stats, API status, tool list, pricing), which is specific enough to understand the tool's scope. It lacks a strong verb like 'retrieve' or 'get', but it does distinguish itself from the yield-focused sibling tools by focusing on system-level metadata.

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 guidance on when to use this tool versus alternatives. While the siblings are yield-related and clearly different, the description doesn't state that this should be used to check API status before running other tools, or similar use cases.

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?

No annotations are provided, but the description discloses a critical behavioral trait: it requires a payment of $0.08 via x402 with an X-PAYMENT header, and notes that new wallets get 5 free units. This is vital for the agent to invoke correctly. It also clarifies the ranking methodology (factoring liquidity, volatility, IL, sustainability). It does not mention rate limits or error handling, but the payment disclosure is a significant addition.

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

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

The description is a single sentence that front-loads the payment requirement (PREMIUM) before explaining the tool's purpose. It includes the call endpoint and header, which are useful. However, the phrase 'The smart way to compare yields' is marketing fluff that adds little value, slightly reducing conciseness.

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 moderate complexity (4 optional params) and complete schema coverage, the description adequately covers the core purpose, the payment requirement, and the endpoint. It hints at the output (ranked pools) but does not detail the return format. With no output schema, this could be more explicit, but it is sufficient for an agent to understand the tool's behavior.

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 4 parameters have descriptions in the schema (100% coverage), so the baseline is 3. The description adds no additional parameter semantics, such as formatting or default behavior beyond what the schema already states. Therefore, 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 description clearly states the tool's function: 'APY adjusted for risk — pools ranked by real expected return after factoring liquidity, volatility, IL, and sustainability.' It uses a specific verb (ranks) and identifies the resource (pools), and the emphasis on risk-adjusted returns distinguishes it from sibling tools like top_yields or yield_scan.

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

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

The description implies the use case (comparing yields on a risk-adjusted basis) but does not explicitly mention when to use it over alternatives or provide exclusions. Sibling tools are not referenced, so the agent must infer when this tool is appropriate from the purpose alone.

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 behavioral disclosure. It reveals that the tool requires payment (x402, $0.05) and mentions the call endpoint and free trial units, which is useful. However, it does not clarify whether the operation is read-only or any other side effects, and lacks info on error responses 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?

The description is somewhat marketing-heavy ('The institutional DeFi layer') but every sentence provides relevant information: premium status, payment method, endpoint, and free units. It is front-loaded with the premium notice and does not waste words, though it could be tighter.

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

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

For a simple tool with one optional parameter and no output schema, the description covers the essential context: what data it returns, the payment requirement, how to call it, and a free trial offer. It lacks details about response format, but given low complexity, it is 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 schema fully documents the only parameter (limit, default 15), so schema coverage is 100%. The description adds no additional detail about the parameter or its behavior, which matches baseline expectations for well-documented 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 that the tool provides 'Tokenized treasury and Real World Asset yields' and lists specific providers (BlackRock, Ondo, Maple, etc.), which distinguishes it from sibling tools like stablecoin_yield or chain_yields. Though it lacks an explicit verb like 'get' or 'list', the intent is apparent.

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

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

The description implies use cases by naming RWA-focused protocols, but it does not explicitly state when to choose this tool over alternatives. No exclusions or comparisons to sibling tools are provided, leaving the usage context somewhat implicit.

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 takes on the full burden and discloses meaningful behaviors: it filters out pools with APY above 200%, requires real TVL, and ranks results by APY. This goes beyond a bare 'get yields' summary, though it does not address edge cases like empty results 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?

The description is two concise sentences: the first states the core purpose, the second adds filtering criteria and a use case. Every word earns its place, and the purpose is front-loaded.

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

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

For a simple read-only tool with no output schema and only three optional params, the description adequately conveys what it does and what filters apply. It does not explain the return format, but the ranked yield list is implied. Sufficient for the complexity level.

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 provides full descriptions for all three parameters (chain, limit, min_tvl), so the baseline is 3. The description adds context about 'real TVL' which reinforces the min_tvl parameter's purpose, but does not significantly extend the schema's coverage.

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 ranks stablecoin yields by APY, with specific filters for real TVL and sustainability (<200% APY). This distinguishes it from siblings like rwa_yield or risk_adjusted by emphasizing stablecoin focus and safety.

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 'Perfect for treasury management' provides a clear use context, implying when to use this tool for safe stablecoin yield searching. It does not explicitly name alternatives or exclusion criteria, but the use case is well-defined.

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 bears the full burden of behavioral disclosure. It adds useful context ('Data from 19K+ DeFi pools via DeFiLlama') but does not explicitly state that this is a read-only operation, how results are sorted, or potential caveats like pool risk or data freshness. This is adequate but not rich.

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 concise sentences: the first states the primary purpose and scope, the second lists filter options and dataset provenance. No word is wasted, and the structure front-loads the most critical information.

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

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

For a simple query tool with optional params and no output schema, the description covers purpose, scope, filters, and data source. It could explicitly mention sorting order or output format, but the task is straightforward enough that these omissions 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 coverage is 100%: every parameter has a description, so the baseline is 3. The description merely restates the filter options (min TVL, chain, stablecoin-only) without adding deeper meaning or usage nuance beyond what the schema already provides.

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 'Get the highest APY yield pools across all chains and protocols,' which is a specific verb-resource pairing and explicitly differentiates from sibling tools like chain_yields by emphasizing global coverage and top APY ranking. It also clearly mentions the filtering dimensions, leaving no ambiguity about what the tool does.

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 explicit usage scenarios via 'Filter by min TVL, chain, stablecoin-only,' giving clear context for how to narrow results. However, it does not mention when to prefer this tool over specific siblings (e.g., stablecoin_yield or risk_adjusted) or any exclusions, so it stops short of a full 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It implies a read-only comparison operation and lists output dimensions, but does not disclose potential quirks (e.g., unsupported protocol names, data freshness, or whether it makes API calls). The description is not misleading, but it lacks rich behavioral context.

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 that front-loads the action, then lists relevant metrics and an example. Every word contributes value, and it is appropriately sized for a simple two-parameter tool.

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 comparison tool with two string parameters and no output schema, the description gives enough context about what the tool produces (average APY, max APY, TVL, chains, top pools). It lacks information about error handling or output format, but the tool's simplicity and the schema's completeness mitigate these gaps. It is complete enough for an agent to select and invoke it correctly in most cases.

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 example protocol names that are also present in the schema, but does not significantly enhance parameter semantics. Both parameters are documented clearly in the schema, leaving minimal additional meaning to be added.

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 ('Compare') and resource ('two protocols'), and lists concrete comparison metrics (APY, TVL, chains, pools). It differentiates from siblings like top_yields or chain_yields by emphasizing side-by-side comparison. The concrete example 'aave-v3' vs 'compound-v3' further clarifies usage.

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

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

The description implies when to use the tool (when comparing two protocols), but does not explicitly name alternatives or state when not to use it. The example provides practical guidance, but there is no explicit exclusion or differentiation from sibling tools.

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

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

With no annotations, the description carries the burden and discloses key behaviors: it is a premium tool requiring x402 payment ($0.03), the HTTP call endpoint, the required X-PAYMENT header, and the free 5-unit allocation for new wallets. It also specifies the returned data fields. It does not mention rate limits or failure modes, but the core behavioral traits 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?

The description is a single dense sentence that front-loads the premium nature and payment requirement. It is efficient with no redundant filler, though the emojis and capitalization add visual noise. All content contributes to understanding the tool.

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 returns APY, TVL, risk, IL, and 30d average; the description lists these without an output schema. It covers the access mechanism (payment, endpoint, header), search capabilities, and free trial. Missing: error behavior or edge cases, but the essential operational context 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by clarifying that 'query' accepts token or protocol name (also symbol) and pool_id is an exact match via DeFiLlama ID. It also indicates that searches work by name, symbol, or pool ID, which enriches the schema's sparse 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 uses a specific verb 'Deep scan' and clearly identifies the resource: 'a specific pool or token'. It enumerates the output metrics (APY breakdown, TVL, risk score, IL exposure, 30d average) and search methods (name, symbol, pool ID), making it distinct from sibling tools like top_yields or chain_yields.

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

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

The description implies use when in-depth details on a specific pool/token are needed, contrasting with higher-level yield lists. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide selection. Payment requirement is stated upfront, which is important use-case context.

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