kairos-signal

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the 'after purchases' timing cue and does not mention rate limits, cost, or response shape, so it adds modest value beyond 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?

Two short sentences, purpose stated first, use case second, with no filler. Every clause earns its place for a tool this simple.

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 whose annotations cover safety and idempotency, the description plus schema is nearly sufficient; 'remaining credits' implies the return value. It lacks any note on units, currency, or failure behavior for an invalid key, which is the only real 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?

There is a single parameter (api_key) with 100% schema description coverage, so the schema already documents it fully. The description adds nothing about the parameter, which matches the baseline 3 when the schema does the work.

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 ('Check ... credit balance') that is unambiguous and clearly distinct from siblings like topup_credits or purchase_data in intent. It does not explicitly name an alternative, so it stops short of the 5 tier.

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 after purchases to see remaining credits' gives a concrete triggering context, which is more than most definitions offer. It provides no explicit exclusions or named alternatives, so it is clear context rather than full when/when-not guidance.

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, closed-world), so the bar is lower. The description adds real behavioral context beyond them: the free-tier 10-record cap, that rejected rows are retained for depin_onchain, and that observation_quality read-time annotations are not covered by original proof hashes.

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 query sentence is front-loaded, but the remainder pivots into dataset-specific caveats about observation_quality and proof hashes that only apply to one dataset, diluting focus for general callers. Some sentences earn their place; others are only conditionally relevant.

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 query tool with an annotation-covered safety profile and full schema coverage, the essentials are present. However, with no output schema, gaps remain around default limit, ordering, and pagination behavior that the description could reasonably address.

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 dataset, limit, and offset, establishing the baseline of 3. The description restates limit/offset and echoes the tier cap ('10 records per query') but adds no format, default, or ordering detail beyond the schema.

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

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

The description states a specific verb and resource: 'Query records from a dataset with limit/offset,' and the title reinforces 'Fetch raw dataset rows.' It is unambiguous what the tool does, though it does not explicitly distinguish itself from siblings like list_datasets or get_data_dictionary.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. It gives context (free tier cap, depin_onchain retention) but never tells the agent when this tool is the right choice versus list_datasets, get_data_dictionary, or purchase_data.

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, non-destructive and non-open-world, so the safety profile is covered; the description reinforces it redundantly but usefully adds the auth fact 'no key' and the behavioral filter that only networks with live data are returned. It stops short of saying anything about pagination or result ordering, which is the remaining gap.

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 compact sentences, led by the purpose and follow-up routing, with no filler or marketing language. The 'Read-only, no key' clause partially duplicates the annotations, which is the only wasted space.

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?

All required parameters are optional and documented, an output schema exists so return values need no elaboration, and the description nonetheless names the returned fields (symbol, name, category, public page). An agent has everything needed to select and call this 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 each of the three parameters (query, category, limit) is already documented, so the schema carries the load. The description's example tickers add a little flavor about query format, but it says nothing extra about category values or the limit default, 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?

The description states a specific verb and resource (look up DePIN networks and Bittensor subnets), narrows the scope to entries with live data, and illustrates the input format with concrete tickers ('akash', 'helium', 'FIL'). It clearly differentiates itself from detail-oriented siblings like get_network by describing itself as the symbol-resolution step.

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 purpose: 'Use it to get the symbol that get_network, get_metric_history and verify_value take.' That names three alternatives and the condition (need to resolve a symbol) that selects this tool over them, so the agent does not have to infer routing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: it is machine-legible, free, and requires no API key, which affects whether and how an agent invokes it. That is real added value over the structured fields.

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

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

Three dense sentences that front-load what it returns (freshness, history depth, coverage, endpoints) and lead with 'ONBOARDING SPEC'. It is tight, though the label and feed enumeration make it slightly list-heavy.

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-param, read-only tool with full annotation coverage and no output schema, the description covers what it answers, its scope, and its cost/auth posture. The only minor gap is the exact return shape, which the description only gestures at with 'machine-legible'.

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 by the rubric. The description correctly implies a parameterless call with nothing to configure, and 'no key' confirms no auth parameter is needed.

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 (metadata about feeds) and enumerates the feeds by name, and quotes the exact question it answers ('how stale is this and how far back does it go'). It is clearly distinguishable from siblings like get_stats or get_metric_history, though the label 'data dictionary' plus the enumerated feeds does the heavy lifting.

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 scope question ('how stale is this and how far back does it go') implies when to consult it, and 'free, no key' tells the agent there is no setup cost. But there is no explicit when-to-use vs. alternative guidance (e.g., vs. get_metric_history or list_datasets), so an agent must infer the routing.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so 'Read-only, no key' mostly restates them (though 'no key' does add auth context). What earns credit is genuinely new behavior: the 20-entry cap, the 'entries: [] with ledger_status not_yet_covered plus covered symbols' edge case, and the explicit paywall boundary that payload bytes are the separate paid derivation_replay product. That is material disclosure an agent could not infer from the annotations.

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

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

Front-loaded with the core purpose and organized by mode (with symbol / without symbol / read-only), with no filler sentences. It is on the long side for one optional parameter, but each sentence contributes a distinct fact (fields returned, truncation limit, empty-result status, paywall boundary).

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, and the description compensates fully: it enumerates the returned fields (time, verify_url, SHA-256, size, collector code hash, fetch status), describes the coverage-list shape, and handles the not_yet_covered edge case. An agent has everything needed to call it and interpret the response.

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 the single optional param already documents case-insensitivity and that omitting it returns the coverage list. The description adds the 'up to 20 recent fetches' limit, but that is return-volume behavior rather than parameter semantics. Baseline 3 is right when the schema carries the parameter documentation.

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 ('Returns the derivation ledger index') and then cleanly splits the tool into its two operating modes: with a symbol (up to 20 archived upstream fetches) and without (coverage list). It also names the sibling it is not — 'To compare a live value with its upstream right now, use verify_value' — so an agent can separate it from verify_value and verify_footprint without opening a schema.

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

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

Explicit routing: supply a symbol to trace one published value to bytes/build, omit it to get the coverage list. It also names verify_value as the alternative for live comparisons, which is the main confusion risk among the verify_* siblings. When-to-use and when-to-use-something-else are both covered.

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/non-destructive, so the closing 'Read-only' is redundant. The description nonetheless adds material behavior beyond the annotations: absent days are omitted rather than zero (a critical semantics trap for an agent), and auth/tier limits are disclosed via the X-API-Key header and window_notice.

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 the return shape, followed by the absent-vs-zero caveat and then the access rules. Nothing is padded and each clause carries distinct 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, the description need not document return fields, and it still covers the non-obvious gaps: observation density per point, missing-day semantics, free-tier window, and API-key authentication. An agent has everything needed to call it correctly and interpret results.

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 symbol, metric and days are already documented with examples and bounds. The description only reinforces the symbol/metric pairing via its example and touches the 7-day default indirectly through tier language; it adds little parameter meaning 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 and resource — 'Returns the daily series for one network metric' — and pins down grain (one point per UTC day) and an example invocation (symbol=AKT metric=GPU_ACTIVE). It is clearly separable from listing tools like get_network, though it never names a sibling explicitly to route against.

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?

Offers contextual guidance about windowing — the free tier serves 7 days and signals it via window_notice, and an X-API-Key header unlocks your tier's window — which tells the agent what to expect but not when to prefer this tool over alternatives such as get_stats or get_network. Usage is implied rather than stated with exclusions.

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 new context: no API key needed, stale readings are filtered by default, and each metric ships a verify_url on the network's own API that can be opened to independently check the figure. That verification path is not derivable from the annotations or 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 sentences, front-loaded with the resource and payload contents, followed by two short behavioral constraints. The opening sentence is long and parenthetical, but every clause carries distinct information and nothing is redundant 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?

An output schema exists, so return values need not be spelled out, yet the description still previews the per-metric shape (value, unit, as_of, freshness, verify_url), which is useful. Combined with the coverage/exclusion notes and the no-key statement, an agent has what it needs; only the alternative-tool routing (get_metric_history, find_networks) is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the schema. The description restates the metric_filter substring behavior and the include_stale default without adding new semantics (e.g., what counts as 'stale', or how max_metrics interacts with filtering). 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 ('Returns the latest first-party measurements for one DePIN network') and enumerates the metric families covered (GPU/CPU capacity, storage, node/hotspot counts, on-chain totals). It also sets a scope boundary ('Market prices are not included'), which helps separate it from a price-oriented tool. It never names the closest sibling, get_metric_history, so the 'latest vs. history' distinction must be inferred from the word 'latest'.

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

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

Usage is implied rather than stated: the agent can infer this is the one-network snapshot tool, and the behavior notes (metric_filter narrows, stale omitted unless include_stale) hint at narrower read patterns. However, there is no explicit 'use this instead of X when Y' guidance, and the pointer to find_networks for resolving tickers lives only in the schema, not the description.

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 safety is covered. The description adds genuinely new context beyond them: 'No arguments, no key' tells the agent no authentication or parameters are needed. It stops short of stating cost or rate-limit behavior, which would round out 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?

Three sentences, return contents front-loaded, routing second, and no filler. The 'read-only' clause is mildly redundant against the annotations, but everything else 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 no-arg, no-auth, read-only stats tool with no output schema, the description covers what it returns, what is excluded, and which siblings handle related queries. Only the absence of cost/credit implications and return-shape hints 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?

There are zero parameters, so the baseline is 4. The description's 'No arguments' declaration is consistent with the empty schema and usefully confirms no input is required; no further parameter meaning is possible.

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 row counts of every dataset) and enumerates the payload: per-dataset counts, total, scope statement, and free-tier limits. It also names the sibling tools it is not (get_network, get_data_dictionary), so an agent can discriminate without opening a schema.

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

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

Explicit routing is given for both alternatives: use get_network for one network's live values and get_data_dictionary for freshness/history depth per feed. This is unambiguous when-to-use and when-not guidance.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description still adds genuinely non-structured information: this operation is free of charge while queries are subject to existing query and daily-call limits. It does not mention pagination or list size 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?

Two short sentences, zero filler, with the what-you-get ('catalog with record counts') front-loaded before the cost caveat. Nothing to trim.

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-param, no-output-schema list tool the description covers what is returned and the cost model, which is most of what an agent needs. It omits whether the catalog is paginated or how large it can be, 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 takes zero parameters and the schema is an empty object, so there is nothing to disambiguate. Baseline 4 applies; no parameter meaning is needed or missing.

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 ('List the current dataset catalog') and adds scope detail ('with record counts'), which distinguishes it from the singular fetch_dataset sibling. It does not explicitly name which sibling to use instead, but the plural-list scope is 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 cost framing ('Browsing is free; existing query and daily-call limits apply') implies this is the cheap discovery step worth doing before fetching or purchasing, but it never states that directly nor names an alternative tool. Usage is implied rather than instructed.

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), yet the description adds substantial non-obvious behavior: which tiers are priced but not purchasable, that purchase_data will return 503 not_yet_deliverable for them, and that grade purchases are conditional on measured-grade availability. This is exactly the kind of consequence-level disclosure annotations cannot express.

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

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

Purpose and pricing are front-loaded, and the long middle sentence about unpurchasable tiers carries genuinely load-bearing information rather than filler. It is denser than it strictly needs to be, packing several product names and caveats into one block, but nothing is redundant.

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

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

For a parameterless listing tool with a full annotation set and no output schema, the description supplies everything an agent needs to call it correctly and to interpret the credit pricing and purchasability caveats. Return shape is not described, but the safety annotations and pricing context make that a negligible 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 takes zero parameters, so per the rubric the baseline is 4. The description introduces no additional parameter detail (none exists), and none is needed for a parameterless lister.

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 ('Browse purchasable products with prices in credits') and immediately clarifies the credit-to-dollar rate. It is clearly distinct from purchase_data and check_balance in intent, but it never explicitly contrasts itself with the potentially-overlapping list_datasets sibling, so an agent must infer the boundary.

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 concrete sequencing rule ('Call after register_agent') and a pre-purchase instruction ('check /v1/credits/pricing before buying'), which steers usage well. It stops short of naming the alternative tool to use when the task is not browsing products (e.g., list_datasets), so the when-not guidance is incomplete.

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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: deliverability is product-specific, data is returned inline, specific key families return 503 by design, and credits do not alter access tier. It does not, however, describe receipt/error behavior or warn that the credit spend is irreversible.

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 action and the return behavior. The parenthetical about a price 'drifting' from its first location is wordy meta-commentary, but the remaining sentences (503 blocked keys, credits buy data not tier) each carry operational 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?

No output schema exists, and the description compensates by stating that data ships inline in the response and that deliverability is product-specific. For a destructive, credit-spending tool the remaining gap is the absence of receipt/charge-failure semantics, but the essentials for correct invocation are 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 product_key, api_key and idempotency_key are already fully documented, including retry semantics. The description only restates that the api_key comes from register_agent and points at list_products for keys/prices, adding little beyond the schema. Baseline 3 applies 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 ('Buy a product with your credits') plus the key outcome ('the data ships inline in the response'), which distinguishes it from siblings like list_products (browse) and fetch_dataset (retrieve). An agent can identify the operation 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 a clear prerequisite (api_key from register_agent), routes pricing lookups to list_products instead of trusting a restated figure, and names a concrete when-not case: the signal_*, dag_* and mcp_unlimited keys are priced but deliberately blocked. It stops short of advising when to prefer a read-only sibling over spending credits.

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 only declare it is a non-idempotent write; the description adds the per-IP rate limit (3 keys/30 days), the degraded fallback behavior past that limit ($0 key still issued and the response says so), and that email is optional. These are behavioral traits not derivable from the annotations.

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

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

Three sentences, front-loaded with the primary action and side effect, then the prerequisite routing, then the optional parameter note. No 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 two-parameter write tool with no output schema, the description covers the trigger conditions, rate limits, degraded-mode behavior, and return-signal ('the response says so'). Nothing required to invoke 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 description coverage is 100%, so the schema already documents both parameters. The description's note that email is optional is already in the schema; it adds no new syntax or format detail, 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+resource ('Creates an API key for this agent') plus the side effect of granting starter credits. It is clearly distinguishable from the read-only sibling tools it names.

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 when a key is needed (purchase_data, check_balance, topup_credits) and when it is not (all read-only tools), which is exactly the routing information an agent needs against the 14 sibling tools.

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

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

Annotations only declare the generic profile (openWorldHint=true, non-idempotent, non-destructive). The description goes well beyond that: credits post automatically once Stripe confirms, the checkout_url is bound to the caller's api_key, $1 = 1 credit, USDC credit requires finalized Base evidence, and the legacy tx_hash is called out as non-substituting.

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 'Add credits.' and every clause carries information (pricing, flow steps, doc link). The inline JSON fragments slightly interrupt readability, but nothing is padding.

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 multi-step payment tool with no output schema, the description covers both flows, the return of checkout_url for card, and the preconditions for USDC, plus an external docs pointer. It omits what a USDC quote returns and how errors surface, which leaves a small 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it fixes amount to the $20/$99 packs with the $1=1 credit rate and explains that from_address must be an already-verified EOA. It does not document the quote/challenge response shape, which the schema also omits.

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 ('Add credits') and immediately enumerates the two supported funding paths (Stripe card, USDC on Base). This cleanly separates it from siblings like check_balance (read) and purchase_data (dataset purchase), so an agent can route without inspecting 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?

The description contrasts the two methods explicitly: card is 'one call' with 'no human step and no wallet needed', while USDC 'requires more work' with a spelled-out verify/sign/quote sequence. It gives clear selection context but states no hard exclusions or failure/retry conditions.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds real context beyond them: the exact truth condition for verified=true, an explicit statement of what it does NOT assert (Bitcoin status, upstream accuracy), the no-key requirement, and the missing-argument fallback. This is unusually rich behavioral disclosure.

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 purpose and truth condition, and every sentence carries content (scope limit, return fields, usage, fallback). It is dense with parentheticals and could be tightened, but nothing is clearly 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?

With no output schema, the description compensates by enumerating the returned JSON fields (row_sha256, merkle_root, row_hash_matches, inclusion_path_reaches_root, verified, proof_url). Combined with scope limits and usage, an agent has everything needed to call and interpret 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?

Schema coverage is 100%, so the baseline is 3, but the description adds semantic meaning beyond the schema by tying expected_row_sha256 and leaf_index to the verified=true condition and the manifest merkle_root. It reinforces rather than merely repeats the field formats.

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 (retained Merkle-membership check for one depin_onchain observation) and scopes it tightly to a single dataset and row, distinguishing it from the sibling verify_value by naming the exact proof type and data domain. An agent can tell what it does 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 when ('when you hold a row from a daily batch and want to show it was committed that day'), a when-not ('Other datasets: unsupported'), and even describes missing-argument behavior (lists days with a proof ready plus an example). It does not name a sibling alternative to redirect to, so it stops short of the top bar.

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, openWorldHint, idempotentHint=false and destructiveHint=false, so safety is covered. The description adds genuine value beyond that: it discloses the exact outbound behavior (one GET to a third-party API) and enumerates failure verdicts such as not_checkable_by_get and no_matching_field, which tell the agent what a null/negative result means.

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 front-loaded sentences: what it does, when to use it, and its runtime footprint. Every sentence earns its place, with only mild redundancy in the trailing "read-only" clause that duplicates readOnlyHint.

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-value shape needn't be re-explained, and the description still names the verdict vocabulary needed to interpret results. It is essentially complete, missing only cost/latency or rate-limit expectations for the third-party 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 coverage is 100% with both parameters documented (metric tied to get_network metrics, symbol as network ticker), so the schema carries the load. The description adds nothing about parameter semantics or valid value ranges, 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: it re-reads the upstream API behind a value and reports JSONPath location, relative difference, and a named verdict set. An agent immediately knows this is a source-verification tool, though the description never distinguishes it from the similarly named sibling verify_footprint.

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 it to check a figure before relying on it" gives a clear triggering condition. There are no exclusions, prerequisites, or comparison to alternatives such as verify_footprint or get_metric_history, so the agent must infer when this is preferable to those siblings.

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