DeFi vault data from pigi.finance: yields, TVL, history and risk ratings across chains.
Scored across 9 tools
Most tools target distinct concepts (hacks, rates, usage, protocol ratings, vaults), and the vault trio (get_vault / get_vault_history / get_vault_stats) is separated by snapshot vs time-series vs aggregate. The main friction is that get_vault takes a pool id while get_vault_history/get_vault_stats take strategy_id, and get_protocol vs list_protocols differ mainly in scope — descriptions warn about both, but the id duality is a genuine trap.
Every tool follows a clean get_/list_ verb_noun pattern (get_hacks, get_protocol, list_vaults, get_vault_stats, etc.) with no camelCase mixing or vague standalone verbs. The scheme is predictable and signals read-only access consistently.
Nine tools is well-scoped for a read-only DeFi intelligence API: four lookup/aggregate endpoints, three vault views, plus rates and usage. Each tool earns its place with no redundant thin wrappers.
The surface covers the core lifecycle a read-only data client needs: discovery (list_vaults, list_protocols), detail (get_vault, get_protocol), history/stats, plus rates and hack context. Minor gaps remain — no explicit way to resolve a vault's pool id vs strategy_id, and no cross-vault comparison or portfolio view — but agents can work around these.
DeFi hack / exploit loss events, plus a reference set of major TradFi banking losses (the dataset behind pigi.finance/hacks). Each event has a date, the protocol or institution, the USD amount lost, and — for DeFi — a type saying what kind of protocol was hit. The summary in the response totals the ENTIRE filtered set (count + total_amount_hacked + date range), so for "how much was lost in X" read summary rather than paging through every event.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Only events on/before this date (YYYY-MM-DD, inclusive). | |
| from | No | Only events on/after this date (YYYY-MM-DD). | |
| sort | No | date_asc (default), date_desc, amount_desc, amount_asc. | |
| type | No | What kind of protocol was hit: DeFi (lending, yield, staking, stablecoins), Dexes, or Bridges. DeFi events only — TradFi rows have no type, so this excludes them. | |
| limit | No | Page size (default 25). | |
| offset | No | Pagination offset (default 0). | |
| category | No | defi, tradfi, or all (default all). | |
| min_amount | No | Only events at or above this USD amount. |
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 explains the event fields and, importantly, that the summary totals the entire filtered set. This is meaningful context for correct interpretation of results, though it omits minor details like default sort or pagination defaults (which 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?
Two dense, well-structured sentences with no filler. The first sentence front-loads the core purpose and dataset scope, and the second delivers a high-value usage tip about the summary field.
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 and no annotations, the description compensates well by specifying event fields and summary fields. It could mention default sort/pagination behavior explicitly, but the schema already documents those, so the description is sufficiently complete for correct invocation.
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% with detailed parameter descriptions and enums, so the baseline is 3. The description adds little parameter-level meaning beyond schema; its main extra note about summary behavior is a result-interpretation hint rather than new 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?
The description clearly identifies the resource: DeFi hack/exploit loss events plus a TradFi banking-loss reference set. It distinguishes this tool from the sibling tools (get_rates, get_usage, get_vault, etc.), which concern different data domains.
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 gives explicit practical guidance: for aggregated loss totals, read the summary instead of paging through events. It doesn't name alternative tools, but the siblings are not competing options for hack data, so exclusion guidance is unnecessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One protocol node's cumulative rating (same formula as list_protocols) with the vaults that counted: each with its published score and band, TVL, and the share of the vault term it carried, largest first (long lists are truncated; items_total says how many there were). Custom-plan callers also get the node's rubric lines (audit & bounty, admin authority, pause authority, operational history, scale). A node id that is not a rated protocol (e.g. a curator) is an error — take ids from list_protocols.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes | Protocol node id from list_protocols, e.g. "aave-v3-ethereum". | |
| chain_id | No | Numeric chain id as a string; counts only the depositing vaults on that chain. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a good job: it discloses result ordering (largest first), truncation of long lists with an items_total counter, conditional output for custom-plan callers, and the error condition for unrated ids. It does not state read-only/auth requirements, but for a read endpoint the disclosed behavior is unusually 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?
Front-loads the core purpose, then layers output fields, truncation, plan-dependent extras, and the error case. Dense but every sentence earns its place; the middle clause about vault fields is slightly overloaded but readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema, the description covers what comes back, how it is ordered, how it is truncated, how custom-plan callers differ, and what constitutes an invalid call. Nothing material is left for the agent to guess.
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 for node_id by requiring it to be a rated protocol id drawn from list_protocols. It does not explain chain_id's scoping effect in prose, but it adds real constraint semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (one protocol node's cumulative rating) and explicitly names the contributing vaults and their fields, so it is distinguishable from list_protocols and get_vault without opening schemas. It also ties itself to list_protocols as the upstream id source.
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 direction on where ids come from ('take ids from list_protocols') and states the when-not case (a non-rated node such as a curator is an error). It does not contrast itself against get_vault or get_vault_stats, but the routing context is otherwise clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DeFi Base Rate (stablecoin + ETH vault-set mean yield) and the 3-month U.S. T-Bill risk-free rate. Returns the most recent ~30 daily points of each series.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. 'Returns' clearly signals a read-only operation, and the description specifies the data window and series. It does not discuss rate limits or auth, but for a zero-parameter data retrieval tool those are less critical; nothing destructive or state-changing is implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, dense sentences with no filler. The first sentence names both resources, and the second sentence states output granularity. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool, the description explains the return content and timeframe. There is no output schema, so the description provides the essential return-value information. A slightly more explicit statement of output format (e.g., date + rate pairs) would be nice but is not necessary for correct invocation.
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 does not need to explain parameter semantics. The empty input schema is fully self-describing, and the description adds meaning by defining what the returned data contains. Per the 0-params baseline, this scores 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and precisely identifies the resource: DeFi Base Rate (with parenthetical definition) and the 3-month U.S. T-Bill rate. It also states the output scope (~30 daily points). This clearly distinguishes get_rates from siblings like get_hacks, get_vault, and list_vaults.
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 makes clear that this tool is for retrieving recent rate series. It does not explicitly state when not to use it or name alternative tools, but the subject matter is unique among siblings, so an agent can infer this is the go-to tool for rates. There are no exclusion conditions to document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Your API request usage for the current calendar month (UTC) and your plan limit.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It usefully adds that the usage is for the 'current calendar month (UTC)' and includes the 'plan limit', but it does not disclose response shape, units, or any potential side effects beyond the inherently read-only nature implied by 'get'.
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, clear sentence that front-loads the core subject ('Your API request usage') and appends the relevant scope ('current calendar month (UTC)') and companion output ('plan limit'). No filler or repetition.
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 parameterless read-only tool, the description provides the essential information an agent needs: what is measured and the reporting period. It could go slightly further by describing the response format, but the low complexity and no-schema context make this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds meaningful context about what is being measured, but there are no parameters to document.
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 resource ('API request usage' and 'plan limit') and identifies the operation as a read of current usage data. It is distinct from siblings like get_rates or get_vault by naming the usage resource, though it does not explicitly name or contrast those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as get_rates or get_hacks. The description only defines what the tool returns, leaving the agent to infer its appropriate context from the resource name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single vault by its pool id (the id field from list_vaults).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Pool id. |
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 communicates a safe read operation via 'Get' and adds the important scoping detail that the id must come from list_vaults, but it does not disclose return shape, error behavior, or any other side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One well-structured sentence with no filler. The key action and parameter source are front-loaded, and every element earns its place.
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 getter with full schema coverage and no output schema, the description is sufficient. It tells the agent what the tool does, what parameter to provide, and where that parameter comes from, leaving no essential gap for correct invocation.
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 adds value beyond the schema by clarifying that the 'pool id' is the same as the `id` field returned by list_vaults, which prevents agents from confusing it with other vault identifiers.
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 a specific verb ('Get'), a specific resource ('a single vault'), and the key selector ('pool id'), which distinguishes it from list_vaults and the other vault-related siblings. Referencing the `id` field from list_vaults anchors its purpose precisely.
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 gives clear usage context: call this when you need a single vault and have a pool id obtained from list_vaults. It does not explicitly state when not to use it versus get_vault_history or get_vault_stats, but those are clearly different operations by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Daily time-series (TVL, APR, APY, risk-adjusted APR = APR minus a penalty from the vault's published 0-100 risk score, 30-day moving averages) for a vault. Use the strategy_id from list_vaults (NOT the pool id).
| Name | Required | Description | Default |
|---|---|---|---|
| range | No | Window: 7D, 30D, 90D, 180D (default 30D). | |
| strategy_id | Yes | Strategy id (strategy_id from list_vaults). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden. It usefully explains the risk-adjusted APR formula and 30-day moving averages, but doesn't disclose response structure, pagination, or other behavioral traits. This is adequate but not fully transparent.
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 the key data content and ending with the critical parameter caveat. No filler or redundancy.
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 a good job enumerating the returned metrics and the adjusted APR calculation. It could describe the exact response shape, but for a simple two-parameter read tool, the invocation-relevant context 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 baseline is 3. The description adds extra value by clarifying that strategy_id must come from list_vaults and explicitly warning against using the pool id, which prevents a common mistake.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource ('vault') and a specific action/result ('Daily time-series') with concrete metrics (TVL, APR, APY, risk-adjusted APR). It doesn't explicitly name sibling tools like get_vault_stats, but the 'time-series' framing differentiates it well enough.
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 a clear and important usage instruction: use the strategy_id from list_vaults, not the pool id. It doesn't explicitly say when to prefer this over get_vault_stats, but the 'Daily time-series' context makes the intended use reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregated stats over fixed windows (weekly/monthly/quarterly/yearly): TVL low/high, APR, APY, and inflows (net TVL change over the window; positive = net inflow, negative = net outflow — a TVL-based figure that also reflects yield earned, not just deposits/withdrawals). Use the strategy_id from list_vaults. Omit period to get all windows.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | One window, or omit for all. | |
| strategy_id | Yes | Strategy id (strategy_id from list_vaults). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clarifies that inflows are a TVL-based net change, explicitly noting that positive equals net inflow and negative equals outflow, and that yield is included—a non-obvious behavioral nuance. This goes beyond the function name and provides valuable context for interpreting results.
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, well-structured paragraph that leads with the core purpose, then details the metrics and the inflow semantics, and ends with usage notes. Every sentence carries information; there is no padding or repetition.
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 no output schema, so the description must convey the return content, which it does (TVL low/high, APR, APY, inflows). It also explains the inflow metric's meaning and the optional period. While it omits details like exact response format or pagination, the information is sufficient for an agent to understand what the tool returns and how to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds value by referencing list_vaults for strategy_id and clarifying the omission behavior for period, which enriches the parameter meaning beyond the schema's basic enum listing.
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 action (get aggregated stats) on a clear resource (vault stats) with defined content (TVL, APR, APY, inflows). It distinguishes itself from siblings like get_vault and get_vault_history by specifying the windowed aggregation, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent to use strategy_id from list_vaults, which is a direct cross-tool reference, and explains that omitting period returns all windows. However, it does not explicitly state when NOT to use this tool or contrast it with alternatives like get_vault_history, so it falls 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.
pigi's cumulative protocol rating for every rated protocol node, in one call: score = 0.6 × the node's own rating + 0.4 × the TVL-weighted mean of the published scores of the vaults that deposit into it (weights fixed by pigi; with no rated vault the node rating stands alone). Band A (safest) .. F from fixed thresholds, score 0-100 higher = safer. Node ids look like aave-v3-ethereum, euler-v2, morpho-blue-ethereum, metamorpho-v1-1, sparklend, uniswap-v3 — use them with get_protocol. chain_id narrows which vaults count, not the protocol term; framework-wide nodes (euler-v2, uniswap-v3) mix chains without it.
| Name | Required | Description | Default |
|---|---|---|---|
| chain_id | No | Numeric chain id as a string, e.g. "1" for Ethereum. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses the exact scoring formula (0.6 own rating + 0.4 TVL-weighted mean of vault scores), the band scale A..F, the 0-100 direction (higher = safer), and that chain_id narrows vaults rather than the protocol term. It omits auth, rate limits, pagination, and update cadence of ratings.
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?
Dense but mostly front-loaded: the purpose and formula come first, with the node-id examples and chain_id caveat following. The node-example list is a little long, but each clause carries semantic content rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain the return values, and it does — defining score, its range and direction, and the band thresholds. It stops short of describing the record shape or how many nodes are returned, but an agent has enough to call and interpret 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?
Schema coverage is 100% and there is only one parameter, so the baseline is already met. The description goes beyond the schema by explaining chain_id's semantic effect — it filters which vaults contribute to the aggregate, not which protocol nodes appear — which the schema's format-only description does not convey.
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 — returns pigi's cumulative rating for every rated protocol node in one call — and explicitly differentiates from the sibling get_protocol by noting node ids are for use with that tool. An agent can distinguish this bulk-listing tool from the single-node tool without opening schemas.
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 'in one call' and the pointer to get_protocol imply when to use this versus the single-node alternative, and the chain_id caveat explains when the parameter changes scope. There is no explicit 'do not use when' statement, but the routing context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List DeFi vaults pigi.finance tracks (across Aave, Morpho, Euler, Uniswap, and more). Each vault carries pigi's published risk rating where assessed: risk_band (A safest .. F), risk_score (0-100, higher = safer) and risk_adjusted_apr (APR minus the score-derived penalty). Filter server-side by asset_class / search (e.g. "USDC") / risk_band / min_risk_score and sort by apr, tvl, risk_score or risk_adjusted_apr, so "best low-risk USDC vault" is one call. Returns a compact page — narrow with filters and paginate; this is not the full dataset. Use the returned strategy_id with get_vault_history / get_vault_stats, and id with get_vault.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | id_asc (default), apr_desc, tvl_desc, risk_score_desc, risk_adjusted_apr_desc. Nulls last. | |
| limit | No | Page size (default 25). | |
| offset | No | Pagination offset (default 0). | |
| search | No | Case-insensitive substring on the vault name, e.g. "USDC", "WETH", "Gauntlet". | |
| chain_id | No | Numeric chain id as a string, e.g. "1". | |
| risk_band | No | Keep only these published bands, e.g. ["A","B"] for low risk. Unrated vaults never match. | |
| age_filter | No | Vault age band, e.g. new, 6mo, 12mo. | |
| apr_filter | No | APR band, e.g. gt_10, lte_10, non_na. | |
| tvl_filter | No | TVL band, e.g. gte_1m, gte_10m, non_na. | |
| asset_class | No | Denomination class: stable (stablecoin vaults), mixed, or non-stable (ETH, BTC, ...). | |
| protocol_name | No | Exact protocol, e.g. "Aave", "Morpho". | |
| min_risk_score | No | Keep vaults whose published risk_score is at least this. Unrated vaults never match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden, and it does so well: it discloses server-side filtering, compact page behavior, pagination necessity, the meaning of risk_score/risk_adjusted_apr, and that not every vault is rated. No side effects are claimed, and nothing contradicts an annotation.
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?
Five sentences, each earning its place: scope, risk-field semantics, server-side filter/sort capabilities, the compact-page caveat, and cross-tool routing. It front-loads the verb and resource and packs a lot of guidance without rambling.
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 12-parameter list endpoint with no annotations and no output schema, this description is unusually complete. It explains the dataset, the risk model, filtering/sorting/pagination semantics, the need to narrow results, and how to follow up with sibling tools using returned IDs. Nothing essential to invoking 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% so the baseline is 3, but the description adds meaning the schema lacks: risk_band ranges A (safest) through F, risk_score has higher = safer, and risk_adjusted_apr is APR minus a score-derived penalty. These definitions directly affect how to use min_risk_score, risk_band, and the risk sort options.
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: 'List DeFi vaults pigi.finance tracks,' names the integrated protocols, and then explains the risk fields that make it different from a generic vault list. The closing sentence routes to get_vault/get_vault_history/get_vault_stats, so the tool's scope is distinct from its 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?
Provides clear context: how to filter, sort, paginate, and combine filters for a 'best low-risk USDC vault' query. It names the follow-up tools (get_vault_history, get_vault_stats, get_vault) but stops short of explicit exclusions such as 'use get_rates for APRs' or 'when not to use this tool.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_protocollist_protocolsget_hacksget_ratesget_usageget_vaultget_vault_historyget_vault_statslist_vaultsSearch 700+ DeFi vaults, compare risk scores, analyze protocols. No API key needed.
DeFi protocol data: TVL, yield pools, and cross-chain analytics
Evidence-backed DeFi yield data for ~17,000 pools: rates, yield sources, 90-day history. Read-only.
Real-time DeFi risk data: health factors, liquidations, stablecoin pegs, utilization. No API key.
Add one secure layer between your agents and this server.
