Yield.xyz AgentKit

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

Annotations already declare non-read-only, non-destructive, non-idempotent, but the description goes well beyond: it discloses that transactions are unsigned, must never be modified, amounts are human-readable strings (not wei), and must be submitted in stepIndex order with confirmation waits. That is exactly the behavioral context annotations can't 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?

Four dense sentences with no filler; the critical non-execution constraint is front-loaded. Slightly dense but every clause (signing, ordering, ERC-4626 discovery) carries actionable weight.

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 an output schema present and annotations covering the safety profile, the description fills the remaining gaps: signing workflow, ordering constraints, confirmation-waiting, and the sibling discovery call for yield-specific options. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3; the description additionally reinforces amount semantics ('1.5' = 1.5 tokens, not wei) and points to yields_get mechanics.arguments.enter.fields[] for discovering yield-specific options like useMaxAllowance/receiverAddress, adding real value over schema alone.

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?

Opens with a specific verb+resource: 'Construct unsigned transactions to stake or deposit into a yield.' This is clearly distinguishable from the sibling actions_exit (which withdraws) without needing to open 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?

Explicitly states this tool does NOT execute and that the user must sign each transaction unmodified, plus ordering (stepIndex) and confirmation-waiting guidance. It lacks an explicit 'use actions_exit instead when...' routing, but the usage context is otherwise strong.

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?

Goes well past the annotations by disclosing that this does not execute, that the user must sign each transaction exactly as returned, that unsignedTransaction must never be modified, that transactions must be submitted in stepIndex order, and that amounts are human-readable strings rather than wei. This is exactly the kind of safety-critical context annotations (readOnlyHint=false, destructiveHint=false) cannot 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 the non-execution warning, then layered with routing and discovery hints. Every sentence carries information, though the final sentence on RWA/ERC-4626 options is dense enough that it competes for attention with the more critical signing constraint.

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 11-parameter, 2-required mutation-adjacent tool with both annotations and an output schema, the description covers the critical gaps: non-execution, signing discipline, step ordering, and the conditional validity of optional fields. Return shape is covered by the output schema, so nothing an agent needs to call this 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 coverage is 100%, so baseline is 3, but the description adds a genuine discovery workflow: optional fields like useInstantExecution, useMaxAmount and receiverAddress are only valid when listed in yields_get → mechanics.arguments.exit.fields[]. It also reinforces the amount-as-string semantics and the outputToken "0x" convention is left to the schema, keeping the gain modest rather than exceptional.

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 and resource ("Construct unsigned transactions to unstake or withdraw from a yield") and immediately scopes the boundary against siblings actions_enter and actions_manage. An agent can distinguish this from the deposit and manage paths 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 explicit routing rules: call yields_get_balances first to verify the staked balance, use actions_manage for PENDING withdrawals carrying a passthrough value, and inspect yields_get → mechanics.arguments.exit.fields[] for yield-specific options. Both the when and the when-not are named with concrete tool alternatives.

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 read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond that by naming the lifecycle states an agent should expect and framing the call as a polling primitive for pending approvals. It does not state polling cadence, rate limits, or terminal-state handling, which would have pushed this higher.

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 short sentences, front-loaded with the core verb-and-resource statement before usage context. Every sentence carries information, though 'Essential for...' has a slightly promotional tone that could be tightened.

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?

An output schema exists, so return values needn't be explained, and the description covers the one input's meaning and the async polling motivation. For a single-parameter read tool this is nearly complete; only error/not-found behavior and polling guidance are 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 coverage is 100% and the actionId description already explains it is the UUID returned by actions_enter, actions_exit, or actions_manage. The description only restates 'by its ID' and adds no format constraints or edge cases. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource: retrieve current status and transactions of a single action, keyed by ID. The status enumeration (CREATED/PROCESSING/SUCCESS/FAILED) makes the resource scope concrete. It does not differentiate from the sibling actions_get_all, so an agent must infer that this is for one action rather than a listing.

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 tells the agent when to use it: polling async execution and semi-autonomous flows where approval takes time. That is a clear usage context. It stops short of naming alternatives (e.g., use actions_get_all to enumerate actions), so exclusion guidance is absent.

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 destructiveHint=false, so safety is covered. The description adds that results include both past and pending actions, which is useful, but it does not describe response shape, ordering, or pagination behavior beyond what the schema already says.

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 list operation and stays to two sentences. The examples are useful, though the filter list is slightly incomplete because it omits network filtering, which the schema supports.

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 the core purpose and common use cases, and the schema fully documents the filters. However, with no output schema, it does not explain what an action record contains or how results are ordered, and it does not clarify the boundary with actions_get.

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 explains all eight parameters, including enum values and status meanings. The description names several filters but omits network, limit, and offset, and adds no detail beyond the schema, so baseline 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 gives a specific verb and resource: listing past and pending actions for a wallet address. It is clear what the tool does, but it does not explicitly distinguish this list operation from the sibling actions_get tool or explain what actions_get returns instead.

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 includes concrete use cases such as showing pending actions, recent activity, and actions waiting for approval. This gives clear guidance on when to use the tool, though it does not name exclusions or alternative tools for related queries.

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 non-execution disclosure ('Construct unsigned transactions ... Does NOT execute — the user must sign') adds real value beyond the annotations, telling the agent the call produces unsigned payloads and that user signing is a required downstream step. This is consistent with destructiveHint=false and readOnlyHint=false. It does not cover what the constructed payload looks like or what happens with a stale passthrough, but the output schema carries the return shape.

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 short, front-loaded sentences with zero waste: purpose first, then the critical non-execution caveat, then the sourcing constraint. Nothing is padded.

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 a full output schema, annotations, and 100% parameter coverage, the description supplies the two things structured fields cannot: the unsigned-transaction semantics and the mandatory upstream source for action/passthrough. The only gap is the sibling boundary against actions_enter/actions_exit.

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 schema already documents yieldId, address, amount, action, passthrough and executionMode sources and defaults. The description's sourcing instruction for action/passthrough restates what the schema fields already say, adding no new semantics.

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 and resource ('Construct unsigned transactions for a pending action') and gives concrete examples (claiming rewards, restaking, unlocking funds). It does not, however, explicitly differentiate itself from actions_enter or actions_exit, which overlap with the STAKE/UNSTAKE values in its own action enum.

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 a strong, explicit precondition: the action type and passthrough must come from yields_get_balances balances[].pendingActions[] and must not be guessed. That is excellent context, but there is no guidance on when to prefer this over actions_enter/actions_exit for the overlapping action types.

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 behavior. The description adds valuable context: polling semantics, the full status state machine, and which states are terminal. It doesn't cover polling cadence or rate limits, but that's a minor gap given the rich 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?

Four tightly written sentences with zero waste. The primary action is front-loaded, and the status list is presented efficiently as an essential reference.

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 polling tool with full schema coverage, an output schema, and rich annotations, the description provides everything an agent needs to call it correctly: purpose, usage context, status meanings, and terminal states.

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 fully documents the single parameter. The description only restates 'by its ID' without adding format or usage details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Poll') and resource ('status of a single transaction by its ID'), and distinguishes itself from sibling submit_hash by naming the prior step. An agent can immediately tell this is for checking transaction status, not for submitting or listing.

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 says 'Use after submit_hash to confirm on-chain success,' giving a clear condition and alternative context. The status enumeration and terminal states further guide interpretation of when polling is complete.

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, open-world behavior, so the safety profile is covered. The description adds that the result is a directory of network identifiers plus names and categories, which is meaningful signal since there is no output schema. It does not say whether the list is paginated or how large it typically is.

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, front-loaded with what the tool returns and immediately followed by the prerequisite use case. No filler or restatement of the title.

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 correctly names the returned fields and ties the tool into a dependency chain with other yield tools. The only omission is that the optional search/category filters exist and can narrow the result, which an agent would only learn from the schema.

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 (search, category) are fully documented with examples and an enum, so the schema carries the burden. The description adds nothing about the filters, not even that filtering is possible, so it does not exceed the baseline.

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 and resource (discover supported networks) and enumerates the fields returned (IDs, names, categories). The framing as a lookup/enumeration tool clearly separates it from sibling list tools such as providers_get_all and yields_get_all.

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 prescribes the use case: resolve valid network slugs before calling yields_get_all, yields_get_balances, or any tool needing a network parameter. This names the alternatives and the condition that selects them, leaving nothing to inference.

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 the safety profile is covered. The description adds value by disclosing the exact return shape (name, id, description, website, TVL, type). It doesn't mention that results are paginated, though the schema handles that.

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, each earning its place: what it returns, why to call it, and how it feeds a sibling. Return-shape detail is front-loaded and no sentence is 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?

For a read-only, two-parameter listing tool with no output schema, the description covers purpose, return fields, and usage context thoroughly. Nothing an agent needs in order to call it 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 coverage is 100% with only limit and offset, both fully documented in the schema. The description adds no pagination or page-size guidance beyond what the schema provides, so 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 ("Discover") and concrete resource (supported protocols and validator providers) with named examples like Lido, Aave, Morpho, and it enumerates the returned fields. The agent can distinguish this listing tool from the yields_* siblings without opening the 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 explicit use cases ("answer 'what protocols does Yield.xyz support?'") and, crucially, names the downstream dependency: valid provider IDs for yields_get_all filters. That connects it to a specific sibling tool with a stated condition.

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=false, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. It adds useful context about the internal status update and tracking enablement, plus the 'once per transaction' guidance that aligns with idempotency. It stops short of describing any authorization requirements or 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?

Three sentences, front-loaded with the action and the timing condition. Every sentence contributes: what to submit, what it does, and how often to call it.

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 two-parameter mutation with full schema coverage, annotations, and an output schema, the description covers the essential call context. It could be slightly richer about what happens on invalid or duplicate hashes, but the core information an agent needs 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 both parameters are already well documented in the schema. The description reinforces where the values come from ('from the broadcast result'), but this adds little beyond what the schema says and may slightly blur that transactionId comes from the action flow rather than the broadcast itself.

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 and resource ('Submit the on-chain transaction hash') and states the effect ('updates the transaction status internally and enables tracking'). It is unambiguous, though it does not explicitly differentiate itself from the only adjacent read tool, get_transaction.

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 clearly states the timing prerequisite ('after the user has signed and broadcasted a transaction') and an invocation rule ('Call this once per transaction'). No alternatives or exclusions are needed because no sibling performs the same action, but the description does not mention what to do if the call fails.

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 and openWorldHint=false, so safety is covered; the description adds real value beyond that by stating the domain restriction ('Only accepts docs.yield.xyz URLs') and characterizing the return as 'authoritative spec with exact field names, types, and examples', which matters since there is no output schema. It stops short of saying what happens on a non-docs URL (error vs. empty) or any size/pagination 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?

Four short sentences, front-loaded with the identity and purpose, followed by usage, return value, constraint, and exclusion. No filler or restatement of the tool name.

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 tool with no output schema, the description covers what it does, what it returns, the input constraint, and the exclusion case. Nothing an agent needs in order to call it 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 coverage is 100% and the single parameter is documented with an example, so the baseline is 3. The description adds a constraint the schema does not encode — that the URL must be a docs.yield.xyz .md page — which meaningfully narrows what a valid value looks like.

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 and resource ('fetches the full markdown content of any Yield.xyz documentation page') and labels itself a BUILDER TOOL, which separates it from the live-API siblings like yields_get_all or actions_get. The agent can tell what it returns (markdown docs) without opening the 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 an explicit sequencing rule ('Use after yield_lookup_docs returns a URL'), naming the sibling that feeds it, plus an explicit exclusion ('Do NOT use this for live API calls or user transactions'), which routes the agent away from the transaction/query tools. Both the when and the when-not are present.

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 and openWorldHint, so safety is covered; the description adds genuinely useful behavior: the live source URL, the partial-match nature of the endpoint filter, and the non-obvious rule that 'all' excludes large component schemas. It does not mention latency, caching, or response size limits for a live network fetch, which keeps it from a 5.

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 intent is front-loaded in the first two sentences, but the closing sentence ('Also use this to look up: what errors can a specific endpoint return, what are the exact parameter constraints, what does a 400/403/422/429 response look like') restates content already given and pads the definition with no new 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?

With no output schema, the description carries the return-value burden and does so: it promises structured field definitions, required flags, and error codes. The only missing element is any hint about response volume or pagination when no endpoint filter is supplied, which matters for a spec of this size.

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 two params have enums, so the schema already documents query, method, section and endpoint thoroughly. The description only echoes the endpoint examples and the 'all excludes schemas' caveat that the schema itself states, adding little new semantics — 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 and resource ('fetches the live Yield.xyz OpenAPI spec') and enumerates what can be retrieved: body schemas, constraints, error shapes, operationIds. It is clear what the tool does, but it never distinguishes itself from similar siblings like yield_fetch_doc or yield_lookup_docs, which an agent could easily confuse with this one.

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 concrete triggers ('Use when you need exact request body schemas, field constraints, error response shapes') and an explicit directive ('Use this instead of guessing field names — the spec is the ground truth'). It lacks any exclusion or routing statement relative to the doc-fetching siblings, 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 and openWorldHint, covering safety and external access. The description adds valuable context beyond that: it says each repo comes with a one-line description and how to fetch raw files, and it warns against live data or transactions. It omits operational details like rate limits or authentication, but these are minor for a public read-only listing.

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 and usage trigger are front-loaded, and the paragraph is information-dense with no filler. It is somewhat long because it enumerates repo coverage and return behavior, though each clause is actionable and could be trimmed only 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?

With no parameters and no output schema, the description carries the missing return information by explaining what each repo entry includes and how to fetch raw files. Combined with annotations for read-only/open-world behavior, it gives the agent everything needed to decide when and how to call 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?

There are zero parameters, so the baseline is 4. The description correctly implies no inputs are needed and does not invent parameter semantics.

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?

It states a specific verb and resource: list public Yield.xyz GitHub repos to use as a code reference. It also distinguishes itself from the docs tools and action tools by naming them and explaining what the repos cover.

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 an explicit trigger: use this when stuck on an integration and other docs tools do not provide enough. It also states when not to use it, directing live data and user transactions to the action tools, and names the sibling tools to try first.

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 the read-only and open-world profile, but the description adds real value beyond them: it discloses that results come from a live index in real time, describes the return shape (page links with title, section, description), and warns about what NOT to do when nothing matches. Minor gap: no indication of how many results are returned or how relevance is ranked, which matters for the 'pick one or two' instruction.

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 audience warning in caps, then the operation, then the follow-up workflow, then example queries. Every sentence carries routing or behavioral information; nothing is a restatement of the name or title.

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-parameter search tool with no output schema, the description covers purpose, return shape, and workflow well enough to call it correctly. The remaining gap is result-set behavior — result count and pagination or narrowing strategy — which an agent would need if the first query returns nothing useful.

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?

With a single parameter at 100% schema coverage, the baseline is 3, but the description earns a bump by showing the kinds of input accepted: natural-language questions ('how does X work'), keyword phrases ('find docs on balances'), and format/spec queries ('Solana signing format'). That illustrates the schema's 'Keywords or natural language question' more concretely than the schema alone.

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 and resource — 'Searches the live Yield.xyz documentation index (llms.txt)' — and immediately scopes it as a builder tool, not for end-user actions or live data. It also names the sibling it feeds into (yield_fetch_doc), so an agent can tell it apart from the action and yields tools 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?

Explicit when-to-use ('developing an integration', with four concrete query examples), explicit when-not ('NOT for end-user actions or live data'), and explicit fallback routing ('use the other docs tools in this MCP (never the action tools)'). It even specifies the follow-up step: pick one or two results and read them with yield_fetch_doc.

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, closed-world behavior, so the description only needs to add context — which it does by naming the metadata dimensions returned and the entry/exit-open flag. It doesn't state behavior for an unknown yieldId or data freshness, keeping it below 5.

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 capability statement is front-loaded and the actionable instruction follows. Every clause (fees, lock-up, cooldown, reward mechanics, open status) maps to a distinct piece of returned 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?

With an output schema present, return values need not be explained, and annotations cover the safety profile. The description is sufficient to invoke correctly, though it lacks guidance on how to source a yieldId or what happens on an invalid one.

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?

Only one parameter with 100% schema coverage and a concrete example ("ethereum-eth-lido-staking"), so the schema already carries the burden. The description adds no format, lookup, or discovery guidance (e.g., how to obtain a yieldId) beyond the schema baseline.

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 (get) and resource (metadata for a single yield opportunity) and enumerates the exact contents: fees, lock-up/cooldown, reward mechanics, entry/exit status. This clearly separates it from siblings like yields_get_risk, yields_get_tvl_history, and yields_get_validators without the agent needing to open 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?

"Show this to the user before they commit to entering a position" gives a clear usage context and a placement in the workflow preceding actions_enter. It does not explicitly name alternatives or exclusions (e.g., use yields_get_all for browsing), 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds real behavioral context beyond that: RWA-type results carry an embedded kyc object with eligibility, tiers, jurisdictions, and authorizeUrl. It does not discuss pagination limits or sort behavior, but those live in the schema.

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, each carrying a distinct payload: purpose, sequencing precondition, filtering summary, and the RWA special case. The most decision-relevant information (use this before yields_get) comes early with no preamble.

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?

No output schema exists, and the description compensates for the main non-obvious return shape by describing the RWA kyc object inline. For a 12-parameter but zero-required discovery tool this is close to complete; only the page-size/offset loop semantics are left entirely to the schema.

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 the baseline is 3; the description earns the extra point by tying the 'types' parameter to a concrete behavioral consequence (real_world_asset yields return a kyc object) that the schema alone does not convey. It also summarizes the filter axes (network, token symbol, type) as a usable mental model.

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?

Opens with a specific verb and resource ('Discover yield opportunities across all supported networks and protocols') and explicitly distinguishes itself from the sibling yields_get, which retrieves a single yield by ID. An agent can tell immediately this is the discovery/list surface.

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 states the downstream dependency: get yield IDs here before calling yields_get, actions_enter, or balance/validator tools. It also gives a clear when-not-to-call rule for RWA yields ('read it directly instead of calling yields_get per yield'), which prevents an N+1 pattern.

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 the safety profile (readOnlyHint, idempotentHint, non-destructive), so the description's added value is the cross-tool dependency and the response path that downstream tools consume. It stops short of describing hydration/refresh behavior or whether balances are live vs cached, but the prerequisite disclosure is the critical piece and is clearly stated.

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, zero waste. The capability statement comes first and the ordering constraint plus its rationale second, so an agent gets the actionable rule immediately after the purpose.

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 does well to name the returned sections (balances, pendingActions) and the exact field path downstream tools need. It could say slightly more about what 'balances' contains or how empty results appear, but for a 3-parameter read tool with full schema coverage this is close to 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?

Schema coverage is 100%, so address, network, and yieldIds are fully documented in the schema itself. The description only adds the framing that querying spans 'one or more yields' (implying yieldIds is an optional narrowing filter), which is marginal beyond the schema — 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 and resource ('Get current balances and pending actions') scoped to a wallet address across one or more yields, which cleanly separates it from the sibling list tools like yields_get and yields_get_all. The mention of the pendingActions passthrough makes the tool's distinctive output explicit.

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 an explicit, mandatory ordering rule: 'Always call this before actions_exit or actions_manage', and names the two sibling tools it gates. It also explains why — the passthrough value must originate from balances[].pendingActions[].passthrough — so an agent knows both when and why to select it.

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 read-only, idempotent and open-world behavior, and the description adds real signal: the "not_required" sentinel value and the conditional authorizeUrl on "not_started"/"pending". It doesn't discuss latency, caching, or error modes for invalid yield IDs, so it's strong but not exhaustive.

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 short sentences with the purpose first, the routing rule second, and the return-value edge cases last. No repetition of the title or schema text.

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 an output schema present and rich annotations, the description need only cover purpose, timing, and notable return cases – all of which it does, including the KYC-gated RWA scenario that motivates the call.

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 both yieldId (with an example) and address are already fully documented. The description adds no parameter-level detail beyond the schema, so the 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 and resource ('Get the normalized KYC status of a wallet address for a yield') and scopes it to a yield. An agent can distinguish it immediately from siblings like yields_get_risk or actions_enter 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?

Explicitly says to call it before actions_enter on yields that gate deposits behind KYC, names concrete RWA examples (Securitize/Superstate), and tells the agent that non-gated yields return "not_required" – effectively the when-not case.

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 disclose that this is a safe, read-only, idempotent operation, so the description does not need to carry the full safety burden. It adds the default time window and sampling interval, but those defaults are also present in the schema, and it does not describe ordering, pagination behavior, or response shape.

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?

It is two tightly written sentences with the core purpose front-loaded, followed by a concrete usage example. There is no redundant or decorative language.

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 rich schema and read-only annotations, the description provides enough to call the tool correctly for APY trend questions. Since there is no output schema, it could be slightly stronger by describing the snapshot return shape, but the core 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 description coverage is 100%, so all seven parameters are already well documented. The description's mention of the default 30-day window and daily interval reinforces the schema but adds no new parameter semantics, making the baseline 3 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 states a specific verb and resource: get historical APY/reward rate snapshots for a yield over time. It clearly distinguishes this from sibling tools like yields_get_tvl_history by naming the exact data being returned and the question it 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?

It gives clear usage context by naming the questions this tool answers (APY stability, APY trends) and states default behavior. It does not explicitly name a sibling alternative or when not to use it, which keeps it below 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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: it discloses the shape of the return content (individual risk items grouped by category such as smart contract, liquidity, counterparty), which is important given there is no output schema.

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 short sentences, each doing distinct work: what it returns, how it differs from the sibling, and when to invoke it. No repetition of the title or 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?

For a single-parameter read tool with annotations covering safety and no output schema, the description supplies the essential missing piece—what the response contains at a high level. It could say more about risk item structure or how invalid yield IDs behave, but nothing an agent needs to call it correctly is absent.

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 yieldId parameter is documented in the schema with a format example. The description adds no further semantics about the identifier, so the baseline 3 for schema-driven parameter documentation 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 names a specific verb and resource ("Get detailed risk parameters for a yield") and explicitly contrasts the scope with the sibling tool yields_get, noting it is "more granular than the risk field." An agent can distinguish this from yields_get without opening either 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?

It gives a concrete trigger ("Use this when the user asks about protocol safety or risk") and implicitly routes detail-seeking queries here rather than to yields_get's summary risk field. It stops short of stating when NOT to call it (e.g. when only a top-level risk score is needed), but the 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is fully covered structurally. The description adds only the default window and interval, which arguably belongs to parameters; it says nothing about data freshness, sampling gaps, or behavior when the range is empty. With annotations present, this is adequate but not additive.

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 short sentences: what it returns, why to call it, and the defaults. The purpose is front-loaded and no sentence is filler. Nothing wasted.

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 is the only place a caller could learn what a 'snapshot' looks like (timestamp plus TVL value, per-protocol breakdown?). With 7 parameters and a paginated data-returning tool, that gap is real. The purpose and defaults are covered, but the return shape is not.

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 including the from/to/period precedence rule is already documented in the schema. The description repeats the default period and interval rather than adding new semantics. Baseline 3 applies since the schema carries the burden.

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 a specific verb and resource — 'Get historical Total Value Locked snapshots for a yield' — which is unambiguous and distinguishable from siblings like yields_get_risk or yields_get_reward_rate_history. It stops short of explicitly contrasting with those neighbors, but the resource is specific enough that an agent can route correctly.

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 to assess protocol health — a declining TVL is a warning sign' gives a rationale for calling the tool, which implies usage. However, there is no explicit when-not guidance, no mention of pairing with yields_get_risk or yields_get_balances, and no statement about what to do when TVL history is unavailable.

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 behavior, so the description only needs to add context beyond that. It does so by scoping results to delegation-based yields only and explaining that preferred=true returns curated/recommended entries, though it says nothing about result ordering or pagination mechanics (the output schema covers the return shape).

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 tight sentences, front-loaded with purpose, then downstream usage, then the curated-validator filter. No filler, no repetition of schema fields.

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 full schema coverage, an output schema, and complete safety annotations, the description carries only the narrative burden — and it covers purpose, domain constraint, and next-step routing. Only the absence of paging/ordering guidance (arguably covered by the schema and output schema) keeps it from a 5.

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 is already documented in structured form. The description reinforces the intended use of the address and preferred filters but adds no syntax, format, or edge-case detail beyond the schema — baseline 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 opens with a specific verb+resource ('List validators') and scopes it to 'delegation-based yields such as Cosmos native staking or ETH native staking,' which cleanly separates it from sibling list tools like yields_get_all or providers_get_all. An agent can identify the tool's job and its domain without opening the 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?

It explicitly states the downstream use ('Use the validator address when calling actions_enter or actions_exit') and a concrete filtering shortcut ('preferred=true to show only curated validators'). It lacks an explicit when-not or prerequisite statement (e.g. what happens for non-delegation yields), 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?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context beyond the annotations: unrecognized errors trigger an automatic live OpenAPI spec lookup, which explains the open-world behavior. It does not describe the shape of the diagnostic response, but adds meaningful process detail.

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-loads the diagnostic purpose, then follows with triggering examples and an important behavior note. The example list is somewhat long but each item clarifies an accepted trigger; no sentence is wasted.

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 two-parameter diagnostic tool with no output schema, the description covers purpose, triggering conditions, accepted input examples, and automatic spec lookup behavior. It could go further by indicating what the diagnosis output looks like or how `context` improves results, but it is largely 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?

Schema coverage is 100%, so the schema already defines both parameters. The description adds semantic value by illustrating accepted forms of the `error` parameter ('422', '400 error', 'rate limited', 'transaction failed', 'FAILED status', 'any error code or message'), helping an agent format the required input. The `context` parameter is not elaborated in the description.

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 ('Diagnoses') and resource ('API errors, HTTP status codes, or unexpected responses from the Yield.xyz API'), clearly identifying this as a troubleshooting tool rather than a data lookup. It is readily distinguishable from sibling tools such as actions_* or yields_get_*.

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 triggering conditions with concrete developer phrases ('I'm getting a 422', 'rate limited', 'why did this fail') and examples of error inputs. It does not state when not to use the tool or name sibling alternatives, but no obvious alternative diagnostic sibling exists.

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