yieldhunter

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds behavioral context beyond that: it is 'research only — non-custodial', it can produce validation errors for unknown sourceChainKey and mentions it does not invent bridge fees, and it notes the output includes rationale for when the raw APY leader differs from the risk-adjusted winner. This is helpful extra transparency, though it doesn't fully describe all edge cases (e.g., what happens if an opportunity ID is invalid). The bar is lowered due to robust annotations, so 4 is fair.

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—a few sentences—with a clear structure: purpose, parameter guidance, output summary, constraint note, and an example. It is front-loaded with the most important info (what it does, how many items), and 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?

Given the tool has no output schema, the description compensates by stating what the return contains (ranked list, comparison table fields, winnerId, rationale bullets). It also covers key constraints (2–5 items, SDK validation error for unknown sourceChainKey, aliases). The annotations cover safety (read-only, idempotent). It doesn't explicitly state what happens on invalid opportunity IDs or other error cases, but given the rich schema (with descriptions on every parameter) and clear output summary, it's quite complete. A 4 is appropriate; a 5 would require explicit error-handling for invalid IDs or other edge 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 value by explaining the relationship between poolIds and opportunityIds (aliases) and telling the agent to use list_yields opportunities[].id values, which is not fully explicit in the schema. It also clarifies that sourceChainKey maps to the agent's current chain and that blank is a validation error, reinforcing the schema enum-like behavior. Since it adds meaningful context beyond the schema, a 4 is justified.

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 does a side-by-side comparison of 2–5 opportunities by risk-adjusted score, and returns a ranked list with comparison fields. It distinguishes itself from siblings like score_opportunity (single scoring) and list_yields (list fetching), and it explicitly mentions the raw APY vs risk-adjusted winner distinction, so an agent can differentiate it from related tools.

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 tells the agent when to use it: for comparing 2–5 opportunities. It provides guidance on parameter source (pass list_yields opportunities[].id values as poolIds or opportunityIds), and it names sibling tool list_yields as the source for the IDs. It also gives a concrete example. This is strong usage guidance that goes beyond generic 'how to call' and covers data sourcing.

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?

The description discloses what the tool returns (summary paragraph, factor bullets, net-yield notes, exitRisk line), notes that it is research-only and non-custodial, and describes validation behavior (e.g., unknown sourceChainKey returns VALIDATION_ERROR). This complements the readOnly/idempotent annotations without contradiction.

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: purpose, chain instruction, return details, validation notes, and an example. Every sentence carries necessary information; there is no redundancy. It is concise given the complexity (6 parameters, aliases, validation rules).

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 all essential aspects: the input parameters and their relationships, the output format, the validation behavior, and the non-custodial nature. It also clarifies the relationship to sibling tools (list_yields) and gives an example. Nothing critical is missing for an agent to use 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?

While the schema already covers all parameters (100% coverage), the description adds valuable context: each alias is explained (poolId, opportunityId, id are the same key), defaults are given for horizonDays and notionalUsd, and validation rules for sourceChainKey are detailed (blank/unknown keys cause VALIDATION_ERROR). This enriches the schema meaningfully.

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 purpose: to provide an agent-readable explanation of why an opportunity received its risk-adjusted score. It also names the specific output (summary paragraph, factor bullets, net-yield notes, exitRisk heuristic) and implies it is distinct from sibling tools like score_opportunity and list_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 explicitly instructs how to invoke the tool: pass list_yields opportunities[].id as poolId, opportunityId, or id. It also gives a clear 'when to use' scenario: when you need to justify a ranking to a human or another agent. This is direct and actionable.

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 carry readOnlyHint=true, idempotentHint=true, destructiveHint=false; the description reinforces this with 'Research only — non-custodial' with no contradiction. Crucially it adds the non-obvious inverted scale ('Higher score = lower protocol risk') and the provenance ('curated priors plus DefiLlama metadata when available'), both valuable beyond what annotations provide.

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?

Purpose is front-loaded in the first line, followed by chaining guidance, scale semantics, provenance, safety note, and a concrete JSON example — all in a compact block. It's efficient with minor redundancy ('Also accepts protocolSlug' repeats what the example and schema already show), keeping it just short of a 5.

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 has non-obvious traits — an inverted score scale, a dual alias parameter, and a chaining dependency — and the description covers all of them. It lists expected output components since no output schema exists, and includes a runnable example. Complete enough for correct invocation, with only minor gaps like explicit when-not-to-use guidance.

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 both parameters (protocol, protocolSlug) are already fully documented with descriptions, examples, and the alias relationship in the schema itself. The description adds marginal value by reiterating the alias ('Also accepts protocolSlug') and the chaining origin, but the schema does the heavy lifting. Baseline 3 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?

States a specific verb-resource pair: retrieves a 'Protocol-level risk card' listing concrete components (age, audit signals, curated known issues, category, score 0–100). It explicitly scopes to protocol-level rather than opportunity-level risk, distinguishing it from score_opportunity and compare_opportunities among the siblings. The purpose is unambiguous and differentiated.

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 clear workflow context: 'Chain: pass list_yields opportunities[].protocolSlug as protocol or protocolSlug', telling the agent exactly where this tool fits in a pipeline and what input to feed it. It also notes the 'Research only — non-custodial' nature. However, it never names an alternative tool or states when NOT to use it, so exclusions are left 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), yet the description goes further: it discloses a possible one-time DefiLlama cache refresh side effect, the kill-switch behavior (health still answers, refresh skipped), the YH_STALE_DEGRADE_SECONDS staleness trigger, and the non-custodial/no-key/no-transaction guarantee.

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 purpose and return contents, then operational caveats. Efficient overall, though the closing 'Research estimates only — non-custodial' line is somewhat boilerplate and could be trimmed.

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 no output schema, the description enumerates the return payload (status, schemaVersion, scoringVersion, feature flags, available tools) and explains the stale-data refresh path, so an agent knows both how to call it and what to expect back.

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?

Zero parameters, which yields the baseline 4. The description still supplies an example input ({}) confirming the empty call shape, adding light value over the empty 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 ('Liveness and capability check for yieldhunter') and immediately enumerates what it returns. It also carves out its role as the entry-point tool distinct from list_yields and the scoring 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?

'Use this first to verify connectivity' and 'Copy-paste path starts here, then list_yields' give explicit ordering guidance and name the follow-on sibling. No explicit when-not-to-use clause, but the entry-point framing is unambiguous.

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=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to restate safety. However, it adds useful behavioral context about error handling (VALIDATION_ERROR for unsupported chains) and what fields like exitRisk mean (heuristic only, not an execution gate). Still, the description is extremely long and includes many behavioral details that may overwhelm; some like 'never invent 0' are helpful.

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 very long (several paragraphs) and covers a lot of detail, but it is front-loaded with the core purpose and uses structured bullets for examples. Some redundancy exists (defaults restated in parameter descriptions), and the sheer length may reduce readability for an agent scanning quickly.

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 an 18-parameter tool with no output schema, the description covers defaults, error behavior, ranking logic, edge cases (like null vs 0 changes), and practical usage examples. The copy-paste path helps agents get started immediately. Nothing essential for calling this tool correctly 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 every parameter already has a description. The tool description adds significant semantic value beyond schema: explains the composite risk score meaning, gives practical bands for minScore, explains diversity default behavior, maxRewardShare edge cases, and how includeFactors avoids a second call. This goes well beyond what the schema's short descriptions provide.

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 explicitly states it ranks stablecoin yield opportunities using risk-adjusted scoring, distinguishes from raw APY ranking, and names the specific chains (Ethereum, Base, Arbitrum). It clearly differentiates itself from sibling tools that compare or explain scores.

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 guidance on when to use this tool ('Prefer this when capital preservation and sustainable yield matter more than headline APY'), gives examples for different risk appetites, and explicitly says not to contrast against max-APY rows. It also names alternatives like sortBy=net_apy for headline yield.

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?

The description discloses return details (APY breakdown, factor scores, net yield, exitRisk heuristic with constraints, warnings, sources) and error conditions (sourceChainKey unknown keys return VALIDATION_ERROR, no invented bridge fee). It also states 'Research estimates only — non-custodial', adding trust context. This goes well beyond the readOnlyHint/idempotentHint 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?

The description is well-structured with clear sections (purpose, chaining, returns, example) and packs essential details. It is slightly verbose due to repeated constraints (e.g., sourceChainKey rules appear in both description and schema), but the redundancy is minimal and serves emphasis.

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 inputs (with aliases and defaults), outputs (detailed return components), error conditions, and caveats (research estimates, non-custodial). It even provides an example call. Given the complexity and lack of an output schema, this is comprehensively 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 descriptions are already detailed, but the overall description adds extra meaning: for poolId/opportunityId it clarifies they are aliases for the same canonical id, and for sourceChainKey it reiterates the valid values and error behavior. The example ties parameters together. This exceeds the baseline of 3 for high schema 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 explicitly states the tool computes a multi-factor risk-adjusted score for a single opportunity from list_yields. It clearly distinguishes from siblings like compare_opportunities (single vs. compare) and explain_score (compute vs. explain). The verb 'Compute' and resource 'multi-factor risk-adjusted score' are specific.

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 indicates this is for a single opportunity and provides chaining guidance (pass list_yields opportunities[].id). It does not explicitly state when not to use it versus alternatives like compare_opportunities, but the context of 'single' and the return type make the usage reasonably clear. An explicit when-not would earn a 5.

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