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

Annotations already declare read-only, idempotent, non-destructive, but the description goes well beyond them: it discloses the x402/USDC-on-Base payment model, the free path via WICKEDAPI_API_KEY, and that an unauthenticated call yields HTTP 402 with a decoded price quote rather than a failure. That payment-semantics detail is exactly the kind of context 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 regime classification are front-loaded, followed by a concrete example, usage routing, and a compact behavior note. Slightly long due to the payment paragraph, but each block (example, exclusion, pricing) 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?

For a read-only computed-metric tool with full parameter documentation and no output schema, the definition covers what it computes, when to use it, the sibling alternative, and the payment/auth edge case an agent must handle. Nothing material 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 symbol, timeframe, period, and class are already documented with defaults and enum-like value lists in the schema. The example URL reinforces the symbol/timeframe/period usage but the description adds no semantics beyond the schema, making baseline 3 correct.

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 computation — "Average True Range (Wilder's) + volatility-regime classification (low/normal/high/extreme by historical percentile)" — for a named resource domain (crypto or stocks). It also distinguishes itself explicitly from the sibling `volatility` tool (implied volatility for BTC/ETH).

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 when you need volatility for position sizing or stops" names the motivating use cases, and "Not for implied volatility for BTC/ETH (use volatility)" gives an explicit exclusion with the correct alternative sibling.

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, open-world, and non-destructive behavior. The description adds important context beyond annotations: pricing via x402 or API key, and that an unauthenticated request returns HTTP 402 with a decoded price in payment_required, explicitly framed as a quote rather than a failure.

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 computation, then immediately provides an example, a usage boundary, and payment behavior. Every sentence contributes to correct selection or invocation, with no wasted 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?

For a one-parameter, read-only trading data tool with no output schema, the description covers data sources, use case, sibling exclusion, and the important payment/402 behavior. 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%, so the symbol parameter is already documented as a required base crypto symbol. The description provides an example call and data sources but does not add further semantic meaning to the parameter itself beyond what the schema already says.

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 computation: spot-vs-perp basis (premium %) with funding-implied annualized carry, and names the exact data sources. It distinguishes the tool from the sibling funding_oi by explicitly saying it is not for raw funding data.

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

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

It gives an explicit use case ('when you want the spot-vs-perp premium and funding-implied annualized carry for a basis trade') and names the alternative for raw funding data (funding_oi). No inference is required to choose between this and the sibling.

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, open-world, and non-destructive behavior. The description adds important payment and auth context: x402 USDC on Base, free with WICKEDAPI_API_KEY, and HTTP 402 with payment_required as a quote rather than a failure.

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 short and front-loads purpose, then usage, then behavioral notes. It has minor redundancy between the first sentence and the 'Use when' sentence, both restating 'cash and buying power per connected account'.

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 one-parameter read tool with rich annotations and no output schema, the description covers purpose, usage boundaries, alternative routing, and payment behavior. Nothing critical is missing 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 schema has 100% description coverage, but the only parameter (user_id) is described merely as 'Required.' The description adds no extra meaning about user_id, so the high schema coverage baseline of 3 is appropriate.

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

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

The description states a specific resource and metric: cash and buying power per connected account, normalized. It also explicitly distinguishes from broker_sync_positions, so an agent can disambiguate 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?

It gives an explicit when-to-use statement ('Use when you want cash and buying power per connected account') and an explicit when-not-to-use with the exact alternative ('Not for holdings (use broker_sync_positions)').

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/open-world, but the description adds genuinely new behavior: x402 USDC-on-Base pricing, the API-key bypass, and the fact that an HTTP 402 with decoded price in payment_required is a quote rather than a failure. That payment/error semantics is not derivable from any structured field. It stops short of describing the normalized return shape or any auth/registration prerequisite tied to broker_sync_register_user.

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

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

Front-loaded with purpose, then usage, then behavior — good ordering, and every section carries signal. Minor redundancy between the opening sentence and the 'Use when you want... normalized shape' sentence, which restates the same noun phrase.

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, so the description should hint at the return shape; 'normalized' is asserted but never unpacked (which account fields, pagination, empty-account behavior). Everything else an agent needs to invoke it correctly — scope, alternatives, payment path, 402 semantics — is present.

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

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

Schema coverage is 100%, so baseline is 3, but the schema itself only says 'Required.' for user_id — it never states that this is a broker-sync user identifier (potentially distinct from a wallet address or registry identity). The description does not compensate for that ambiguity.

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 a user's connected brokerage accounts') with a scope qualifier ('normalized'). The description also names the two nearest siblings (broker_sync_positions, broker_sync_balances) it is not, so an agent can discriminate 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?

Gives an explicit when-to-use clause plus two explicit exclusions routed to alternate tools ('Not for holdings (use broker_sync_positions) or cash (use broker_sync_balances)'). This is the strongest form of sibling 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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: it is openWorld and priced via x402 USDC on Base, and critically that an HTTP 402 with payment_required is a price quote rather than a failure. That last detail prevents an agent from misclassifying a normal response as an error, which annotations 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-loads the payload in the first sentence, then labels the routing rule and the behavioral notes explicitly ('Use when', 'Not for', 'Behavior:'). Three short blocks, no filler, and the most decision-relevant content comes first.

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 sketch the return ('real positions ... one normalized schema, stamped as_of'), which is enough for an agent to know what comes back. It stops short of naming any position fields or the shape of the multi-brokerage aggregation, which is the only remaining gap for a single-parameter read tool.

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, and schema description coverage is 100%, so the baseline is 3. The description adds no meaning about user_id itself (e.g. that it is the broker_sync-registered user id from broker_sync_register_user), so nothing is gained 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 resource (real broker positions across all connected brokerages) plus the key differentiator (one normalized schema, stamped as_of). It explicitly contrasts itself with broker_sync_balances, so an agent can distinguish it from the sibling 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 positive condition ('Use when you want a user's real positions across all connected brokerages in one schema') and a negative one with the named alternative ('Not for cash and buying power (use broker_sync_balances)'). That is when-to-use, when-not-to-use, and the substitute in two sentences.

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, and the description goes beyond them with operationally critical context: pricing is x402 (USDC on Base) or free with an API key, and an HTTP 402 is a price quote rather than an error. That last point prevents an agent from misinterpreting a payment challenge as a failure.

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 blocks — what it is, when to use it versus the alternative, and how it behaves/pays — with the scope front-loaded. Every sentence carries distinct information; no restatement of the title or annotations.

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?

Complete enough to call correctly: no params, safety covered by annotations, and the payment path explained. The only mild gap is that it doesn't describe the shape of the returned registry (e.g., per-firm method/status fields), which matters slightly since there is no output 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The description appropriately spends no words on parameters and focuses on scope and payment behavior instead.

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 — a registry of prop-firm platform integrations with live-verified method names (ProjectX, MatchTrader) and connection status. It also explicitly differentiates itself from the nearest sibling, broker_sync_connections, so an agent can route correctly 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?

Gives an explicit when-to-use ("registry of prop-firm platforms and which integration methods are live-verified") and an explicit when-not-to-use with the named alternative ("Not for a user's own accounts (use broker_sync_connections)"). Nothing is left 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?

The description adds meaningful behavioral context beyond annotations: it states that the tool writes state upstream and requires credentials or a wallet signature where applicable. This complements readOnlyHint=false and openWorldHint=true. It does not elaborate on non-idempotency or what happens if the user already exists, but annotations already declare idempotentHint=false.

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 purpose and usage, then behavior, with no major digressions. The phrase 'noted above where applicable' is slightly vague and boilerplate-like, keeping it from a perfect conciseness score.

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 registration tool with no output schema, the description covers purpose, usage, side effect, and the returned portal URL. The main remaining gap is that it does not specify behavior when user_id already exists or exactly which credentials are needed, but annotations cover the core safety profile.

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 sole user_id parameter is well documented in the schema as the application's stable identifier for the end user. The description does not add parameter-specific semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific action (register a user with SnapTrade) and a concrete outcome (get a brokerage connection-portal URL). It also distinguishes this onboarding flow from reading data for an already connected user, which separates it from sibling read tools like broker_sync_balances and broker_sync_connections.

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 explicit when-to-use guidance (onboarding a user who needs a SnapTrade connection-portal URL) and a clear when-not condition (reading data for an already connected user). It does not name the specific alternative sibling to use for reading data, so it falls just short of full alternative 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), and the description goes beyond them with non-obvious operational detail: pricing via x402/USDC, free with an API key, and that a 402 response is a price quote rather than an error. That last point prevents an agent from misclassifying a normal outcome as failure.

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 one-line scope, then usage/routing, then behavior. Every sentence carries distinct load: the 402 clause in particular is the kind of detail that is expensive to rediscover at call time.

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 3-parameter read tool with no output schema, this is nearly complete: it names the resource, the alternative, and the payment/auth failure mode. The only gap is that the shape of a transaction record on success is left unspecified, so an agent cannot predict the response fields.

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 user_id, from, and to are already documented with date format. The description adds no parameter-level meaning (e.g., default date window or per-broker ID semantics), so the baseline of 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 resource (transaction/activity history) and its scope (across brokerages), and explicitly names the sibling it must not be confused with (broker_sync_positions for holdings). The bracketed API tag further disambiguates it within a large tool list.

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 when you want a user's transaction and activity history across brokerages" gives the positive trigger, and "Not for current holdings (use broker_sync_positions)" gives the exclusion plus the named alternative. Both directions of routing are covered with no inference required.

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/open-world, and the description adds real context beyond them: redundant RPC sourcing, the wei-plus-formatted return shape, and the x402 payment flow — including that an HTTP 402 with payment_required is a price quote rather than an error, which prevents an agent from misreading a non-failure.

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 tightly organized (example, usage, behavior). There is mild redundancy — the first sentence already implies the 'Use when' restatement of chains and tokens — but the payment caveat earns its 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?

No output schema exists, yet the description states the return format (wei plus formatted units), the chains, the inputs, and the auth/payment outcomes. An agent has everything needed to call it and interpret results 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 baseline is 3; the description earns an extra point by naming the supported chain values, the default (base, also in schema), and providing a concrete example call with both parameters populated. It stops short of adding format constraints 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 (native-token balance) plus the supported chains and input types (address or ENS). It also explicitly distinguishes itself from siblings chain_token_balance and wallet_portfolio, so an agent can route without opening another 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?

"Use when you need the native-token balance... Not for token balances (use chain_token_balance) or a full holdings view (use wallet_portfolio)" gives explicit when, when-not, and named alternatives. Routing is fully determined.

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, but the description adds genuinely new context: pricing is x402 (USDC on Base) or free with WICKEDAPI_API_KEY, and a 402 response is a price quote rather than a failure. That distinction prevents an agent from misreading a payment challenge as an error.

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 purpose and fields, then example, exclusions and payment behavior in a scannable order. The payment sentence is a bit long but earns its place; the example URL is short and useful.

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-optional-param read tool with no output schema, the description fully compensates by enumerating returned fields, defaults, and the 402 edge case. Nothing an agent needs 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 description coverage is 100% and both parameters already document accepted values and defaults, so the description only reinforces defaults ("latest" for block, base for chain) rather than adding syntax or edge cases. Baseline 3 is appropriate when the schema carries the parameter 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?

Opens with a specific verb+resource ("Block header lookup") and enumerates exactly the returned fields: number, hash, timestamp, miner, tx count, gas used/limit, base fee. It also names the sibling it is not (chain_tx), so an agent can separate it from a transaction lookup 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?

States the selection condition ("Use when you need a block header ... latest by default") and an explicit exclusion with the alternative: "Not for a single transaction (use chain_tx)." Acceptable block selectors (number, latest, safe, finalized) are spelled out, leaving little 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 readOnlyHint, idempotentHint, and openWorldHint, and the description does not contradict them — it confirms "read-only." Beyond annotations, it discloses the payment model (x402 USDC on Base or free with an API key) and explains that an HTTP 402 contains a decoded price quote rather than being a failure, which is exactly the non-obvious behavior an agent needs to avoid misinterpreting the response.

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 definition is front-loaded with the core purpose, followed by an example and then operational behavior. The "either direction" phrasing and the subsequent "Use when you need to resolve..." sentence repeat the same point slightly, but the overall text is efficient and every remaining sentence 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 two-parameter read-only lookup with no output schema, the description covers purpose, directionality, an example, payment behavior, and the 402 response semantics. It does not explicitly state the return shape (e.g., resolved address string vs. primary name), though the bidirectional framing strongly implies it, leaving 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?

Schema description coverage is 100%, so the schema already explains both parameters, including optionality and the name-or-address requirement. The description adds directionality and a concrete `/v1/chain-ens?name=vitalik.eth` example, but it does not clarify the schema's internal inconsistency between `required: ["name"]` and the `name` field being marked optional. 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 states a specific verb and resource — ENS lookup on Ethereum mainnet — and explicitly covers both directions (name→address and address→primary name). It also rules out the adjacent non-ENS lookup case, so an agent can distinguish it from chain_balance, chain_tx, and other chain 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?

It gives a clear when-to-use statement (resolving ENS names or reverse-resolving addresses) and an explicit exclusion ("Not for non-ENS lookups"). It stops short of naming an alternative sibling, but there is no other ENS tool in the sibling list, so the routing guidance is effectively 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 readOnlyHint/idempotentHint/openWorldHint, so the description goes further by disclosing the paywall: x402 USDC on Base, free with an API key, and that a bare HTTP 402 carries a price quote rather than a failure. That last point is genuinely useful behavioral context an agent could otherwise misread as an error, though failure modes for an unresolvable ENS name or bad chain are not described.

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 usage are front-loaded before the example and pricing details, and every sentence is on-topic. The pricing sentence is slightly long relative to its value, but it earns its place because the 402 behavior is counterintuitive.

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 definition covers what is returned at a conceptual level (confirmed plus pending nonce) and explains the payment path. It does not name the response field names, which would be the remaining gap for an agent parsing the result.

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%, documenting both address (0x or ENS) and chain (with the five supported values and base default), so the description need not repeat them. The worked example reinforces the shape of a call but adds no new constraint beyond the schema — baseline 3.

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 — transaction count (nonce) for an address or ENS name — and specifies that both confirmed and pending nonces are returned. The phrase 'Not for balances' explicitly separates it from chain_balance and chain_token_balance among the siblings.

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

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

'Use when you need an address's confirmed and pending transaction count before building a transaction' gives a clear triggering condition, and 'Not for balances' gives an exclusion. It stops short of naming the specific alternative tool (chain_balance) the way an ideal definition would, but the intent is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds critical context those cannot: pricing is x402 USDC on Base or free with an API key, and an HTTP 402 with payment_required is a price quote rather than a failure. The note that symbol and decimals are read from the contract also signals an extra on-chain call and its latency implications.

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 purpose sentence, then example, then usage routing, then behavioral notes — a sensible order with no filler. The long example URL takes significant space for what it conveys, keeping this just short of ideal.

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 three-parameter read tool with full schema coverage and no output schema, this covers purpose, alternatives, chains and the paywall failure mode. The only gap is the exact shape of the returned balance/symbol/decimals payload, which is implied but not spelled out.

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 goes further with a worked example URL showing a real address, token contract and chain=base, plus restating that an ENS name is acceptable for address. That is modest added value rather than new semantics, since defaults and chain values already live in 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 (ERC-20 token balance for an address or ENS name) plus supported chains, and explicitly names the two sibling tools it is not (chain_balance for native, wallet_portfolio for holdings). An agent can distinguish it from every sibling 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?

'Use when you need the balance of one ERC-20 token for an address or ENS name' gives the positive condition, and 'Not for native balance (chain_balance) or everything a wallet holds (wallet_portfolio)' gives the exclusions and the exact alternatives to route to.

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 important context beyond annotations: the x402/USDC pricing model, API-key alternative, and the HTTP 402 quote behavior, which is explicitly framed as a price quote rather than a failure.

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 purpose, followed by a compact example, usage boundaries, and payment behavior. Each section adds useful information without wasted 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?

There is no output schema, but the description lists the returned transaction fields. Annotations cover safety traits, and the description covers the unusual payment/402 behavior, leaving no major gaps 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%, so the schema already documents hash and chain thoroughly, including the default chain and accepted values. The description's example reinforces usage but does not add parameter 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?

The description states a specific verb and resource: transaction lookup by hash, and it enumerates the returned fields (status, block, from/to, value, nonce, gas, logs). It also explicitly distinguishes itself from account-level siblings chain_balance and chain_nonce.

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 clear when-to-use condition: when you need status and details of a transaction by hash. It also gives a when-not-to-use condition and names the alternatives to use for account-level 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 read-only, idempotent, open-world, non-destructive behavior, and the description adds important operational context about x402 payment, API-key access, and HTTP 402 with a decoded price that is not a failure. It does not cover rate limits or pagination behavior, but the payment/auth disclosure is substantive 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?

The definition is front-loaded with the core purpose, then example, usage, and behavior, which is easy to scan. It repeats 'newest first' and includes some nonessential framing, but most sentences carry useful information.

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

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

For a simple read-only news search with no output schema, the description is complete: it lists return fields, names sources, explains filtering, gives an example, and covers auth/payment behavior. Nothing critical for correct invocation 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 q, limit, and source are already documented in the schema. The description mentions keyword/source filtering and gives an example with q and limit, but it adds little semantic detail beyond what the schema already provides.

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

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

The description states a specific resource and verb-like capability: latest crypto headlines aggregated from named outlets, newest first, with listed fields. It also explicitly distinguishes the tool from market data, so an agent can route news queries correctly 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 gives a clear use case: latest crypto headlines from major outlets, newest first, and an exclusion: not for market data. It does not name a specific alternative market-data sibling such as price or ohlcv, so it falls short of the strongest 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?

Beyond the readOnly/idempotent annotations, the description discloses the payment model (x402 USDC on Base, or free with an API key) and, critically, that an unauthenticated call returns HTTP 402 with a decoded price quote rather than an error. That prevents an agent from misclassifying a normal paid response as a failure.

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?

Structure is strong: capability line, example, usage routing, then behavioral notes. The second sentence partly restates the first (repeating the three views), a small redundancy that keeps it short of perfect.

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 should ideally hint at the return shape (e.g. a ranked list of chains with TVL values), which it does not. Everything else an agent needs — scope, exclusions, cost/auth behavior — 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 view/chain/limit/project are already documented, including defaults and max. The description adds only an example query string (`?view=chains`), 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?

First line names the source (DefiLlama) and the three concrete resources: TVL by chain, stablecoin circulating supply, yield pools. The example endpoint plus the explicit exclusion of protocol-level risk data makes it distinguishable from siblings like protocol_health_score.

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 when you need DeFi TVL by chain, stablecoin supply or yield pools" states the selecting condition, and "Not for the health or risk of one protocol (use protocol_health_score)" names the alternative and the boundary. Both when-to-use and when-not-to-use are explicit.

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 safety (readOnlyHint=true, destructiveHint=false), and the description adds genuinely new behavioral context: the Nasdaq live source, x402 USDC-on-Base pricing, free-with-API-key path, and — critically — that an HTTP 402 carries a decoded price quote rather than being a failure. That last detail prevents an agent from misreading a paywall response as an error.

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 resource and field list, then example, then when-to-use/alternatives, then behavior. Every sentence carries distinct information; nothing restates the schema or annotations redundantly.

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, but the description compensates by enumerating the returned fields, so an agent knows what it gets back. Combined with payment and error-path disclosure, nothing needed 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 the baseline is 3. The description adds value beyond the schema by threading date and days together in a concrete example (`?date=2026-07-14&days=3`), clarifying that days is a forward scan window from date. It stops short of explaining how symbol interacts with the range, which the schema only lightly covers.

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 ('US equity earnings announcement calendar') and enumerates the exact fields returned (report date, BMO/AMC timing, EPS estimate + count, market cap, prior-year EPS). Explicitly distinguishes itself from macro_calendar and filings_search by name.

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 when you want upcoming US earnings dates, timing and analyst estimates' gives the positive condition, and 'Not for macro events (use macro_calendar) or filed reports (use filings_search)' names both alternatives and the conditions that select them.

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 openWorld, but the description adds genuinely new operational context: x402 USDC-on-Base pricing, API-key bypass, and that an HTTP 402 is a price quote rather than a failure — a critical distinction an agent would otherwise misread as an error. It also notes each event carries every item with its official label. Minor gap: no rate limits or row-volume expectations beyond the schema's limit cap.

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 actionable classification list, then a usage line, then the exclusion, then payment behavior — a sensible order with no filler sentences. The category enumeration is long but earns its place because it substitutes for a missing enum; the schema-pointer phrasing 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?

With six optional parameters and no output schema, the description needs to convey the response shape and it does at a high level ('each event lists every item with its official label'), plus it explains the payment/auth failure mode. It stops short of describing pagination/cursor semantics or the freshness of classified events, which is the main remaining gap for a data-feed tool.

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 would be 3, but the description adds value the schema lacks: the full valid set of category values (the schema only says 'One of the category names above' and defines no enum). That enumeration materially improves the chance of a correct category filter. It adds nothing for days/since/wait/limit, which the schema already documents.

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 ('8-K material-event alerts') and immediately scopes it as 'classified into categories an agent can act on', then enumerates the 15 categories. It also names the sibling it is not ('Not for all form types (use filings_search)'), so an agent can distinguish it 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 when-to-use ('Use when you want 8-K material events already classified') and an explicit exclusion with the redirect to filings_search. It adds a concrete call example (`?category=bankruptcy&days=7`) that shows the intended filtering 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 declare read-only, idempotent and non-destructive, but the description adds material context they don't cover: x402 pricing in USDC on Base, free with an API key, and that an unauthenticated call returns HTTP 402 with a decoded price in payment_required rather than being a hard failure. That paywall/error semantics is exactly the kind of behavior an agent cannot infer from 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?

Front-loaded with the core definition, then a concrete example, then the routing rule, then the payment/behavior note. Every block is short and purposeful, with 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 single-parameter, no-output-schema read tool, the description covers what is returned, how to identify the resource, when to prefer a sibling, and the notable 402 payment path. Nothing an agent needs to invoke it successfully 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% and the single parameter is already documented with an example in the schema. The description's inline example accession and curl-style path only restate that example, adding no new semantics such as format validation or normalization rules. Baseline 3 is appropriate when the schema carries the meaning.

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 (one filing) keyed by accession number, plus what comes back (parsed items or insider transactions and the SEC document link). It explicitly distinguishes itself from filings_search, so an agent can route correctly 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?

Names the precondition ('when you have an accession number') and the exclusion ('Not for searching (use filings_search)'), pointing at the exact sibling to use instead. This is explicit when/when-not/alternative 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 readOnlyHint, idempotentHint, openWorldHint and non-destructive, but the description adds genuinely new operational context: the endpoint is free and needs no key or payment. It also discloses the measurement definitions (lag measured from SEC acceptance time, sampled over the last 200 live filings), which the annotations cannot convey. It stops short of stating caching or refresh cadence of the poller itself.

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 sentence is repeated verbatim, so roughly half the text is dead weight, and the duplication sits before the useful example and usage guidance. What remains (example, when-to-use, when-not, behavior) is well ordered and front-loaded once the redundancy is skipped.

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 enumerate the returned metrics, and it does so precisely, plus it covers cost/auth. The only gap is that it does not indicate whether the figures are cached or how often they update, which matters for a tool whose entire premise is staleness measurement.

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

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

Zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. The `/v1/freshness` path reference is a harmless extra hint about the underlying endpoint.

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 resource (SEC filings feed freshness) and enumerates exactly what it reports: seconds since last successful poll, newest filing age, median/p95 ingest lag, per-form-type last poll, and row counts. It also explicitly separates itself from filings_search, which serves the filings themselves.

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 when you want proof the SEC feed is live" gives a positive trigger, and "Not for the filings themselves (use filings_search)" names the concrete alternative for the adjacent need. The required/not-required split is unambiguous.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, and the description adds genuinely new context beyond them: it discloses the payment model (x402 USDC on Base or WICKEDAPI_API_KEY) and pre-empts a common misinterpretation by explaining that an HTTP 402 carries a price quote, not a failure. The "Behavior: read-only" line merely restates annotations, which keeps this 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?

Front-loaded with the substantive content rollup and the sibling exclusion, followed by an example and payment note; every block is useful. Minor waste in the redundant "Behavior: read-only" restatement and a fairly dense opening sentence.

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 fully enumerates the returned fields (counts, dollar totals, net flow, distinct buyers/sellers, cluster flag, largest trades), covers the payment/error path, and covers both parameters. 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% and the schema already documents both the required ticker and the days window including default 30 and max 90. The description adds only an example query string, not additional semantics such as ticker format or window edge behavior, 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 — an insider-activity rollup for one ticker over a window — and enumerates the concrete contents (buy/sell counts, dollar totals, net flow, cluster-buying flag, largest trades). It also names the sibling it is not, filings_insider_trades, so an agent can distinguish it 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?

Explicit when-to-use ("Use when you want a ticker's insider buying and selling rolled up over a window") plus an explicit exclusion and routing to the alternative ("Not for the underlying trades (use filings_insider_trades)"). Nothing is left 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?

Beyond the read-only/idempotent annotations, it discloses the default filtering behavior, the pricing model (x402 USDC on Base or API key), and crucially that a bare HTTP 402 carries a price quote rather than being a failure — a behavior an agent would otherwise misread as an error.

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 resource and row shape, then field list, then a worked example, then usage and behavior. The example URL and behavior paragraph are useful rather than padding, though the field enumeration is slightly redundant with the schema.

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-param, no-output-schema read tool, it covers defaults, scope, alternatives, and payment/auth failure semantics. Return shape isn't described (cursor/pagination lives only in schema), but with annotations and 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 baseline is 3; the description adds meaning on top by decoding the transaction codes (P/S/A) and restating the open-market default that governs all_codes. It doesn't add much for the cursor/wait long-poll semantics, but that's already fully documented in 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?

Specific verb+resource: 'Form 4 insider transactions parsed to one row per trade', and it enumerates the per-row fields the agent will get. It explicitly contrasts with filings_insider_summary, so an agent can pick between them without inspecting 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?

'Use when you want individual Form 4 insider transactions, one row per trade. Not for a per-ticker rollup (use filings_insider_summary)' gives both the selecting condition and the named alternative. It also states the default scope (open-market buys and sells only), which shapes when this tool is appropriate.

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, non-destructive, so the safety profile is covered. The description adds genuinely useful non-schema context: it is free, requires no key or payment, and is capped at 10 records — none of which the annotations 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?

The opening sentence is immediately duplicated almost verbatim ('The 10 most recent filings across all form types (form, company, ticker, filed_at only) - Free.' followed by the same phrase), wasting space. The remaining example, exclusion and behavior lines are well front-loaded but the redundancy costs 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?

With no output schema, the description compensates by enumerating the returned fields (form, company, ticker, filed_at) and the 10-record cap, and it discloses the free/no-key terms. Complete enough to call correctly; only the result ordering/pagination edge is unstated.

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 there is nothing for the description to disambiguate; it simply confirms the no-argument nature with an example path (/v1/latest-preview). Baseline 4 applies for a parameterless tool.

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 (10 most recent filings across all form types) plus the exact fields returned, and implicitly scopes it as a free preview versus the paid full endpoint. An agent can distinguish it from filings_search 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?

Explicitly says when to use it ('when you want a free glimpse of the 10 most recent filings') and when not to ('Not for full structured data (use filings_search)'), naming the alternative sibling directly.

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 beyond the annotations by disclosing ingestion latency (~1 minute from SEC acceptance), pagination via cursor and long-poll semantics with wait=, and the x402/API-key access model including that HTTP 402 carries a decoded price quote rather than being a failure — that last point materially prevents an agent from misreading an error. Slightly short of 5 because it doesn't state rate limits or response envelope 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?

Front-loaded with the resource and freshness promise, then usage routing, then behavior/pricing — a sensible information hierarchy. Minor redundancy: the form-type list (8-K, Form 4, 13D/13G, 10-K, 10-Q) is repeated verbatim in the opening sentence and again in the 'Use when' sentence.

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 eight-parameter read tool with no output schema, the description covers what an agent needs: filter surface, pagination/polling mechanics, latency expectations, and payment/auth paths including the non-obvious 402-as-quote case. Nothing required 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%, so all eight parameters are already documented with defaults and ranges (days default 2/max 90, wait max 25, limit max 200). The description only restates the parameter names in prose ('form, ticker, CIK or 8-K item', 'page with a cursor, or long-poll with wait='), though the inline example does helpfully show day-scoped item 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?

States a specific verb and resource ('Structured SEC filings feed') with an explicit form-type enumeration and freshness guarantee ('ingested within about a minute of SEC acceptance'). It also names the two sibling tools it is *not* (filings_8k_events, filings_insider_trades), so an agent can disambiguate 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?

Provides an explicit 'Use when...' condition (structured filings filtered by ticker/form/time) plus explicit exclusions routing to filings_8k_events for classified event alerts and filings_insider_trades for insider trades. Nothing about tool selection is left 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 read-only/idempotent/non-destructive, and the description goes well beyond them by disclosing the pricing model: x402 (USDC on Base) or free with an API key, and that an unauthenticated call returns HTTP 402 with `payment_required` as a price quote rather than a failure. That preempts a very likely agent misinterpretation of a 402 response.

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 purpose, then example, then usage/exclusion, then behavior — a clean hierarchy where each block earns its place. Minor waste in the bracketed `[Trading Data API]` prefix and some bold/formatting overhead, but nothing substantive 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?

No output schema exists, so the description compensates by naming the returned metrics (7d avg funding, 24h OI change, bias signal) and the aggregation sources. Combined with the payment-failure behavior and a single well-documented parameter, an agent has everything needed to invoke and interpret 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% and the `symbol` parameter is already documented in the schema, including the SYMBOLUSDT perpetual mapping. The description only adds a concrete example URL (`/v1/funding-oi?symbol=BTC`), which is mildly useful but not semantic depth 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+resource: aggregates perpetual-futures funding rate and open interest from Binance and Bybit, and names the derived fields (7d avg funding, 24h OI change, long/short bias). It explicitly distinguishes itself from the `hyperliquid` and `basis` siblings, so an agent can route 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?

Gives explicit when-to-use (gauge leverage and crowding) and two concrete when-not-to-use cases naming the correct alternatives: Hyperliquid-specific data → `hyperliquid`, spot-vs-perp carry → `basis`. This is exactly the routing guidance an agent needs among ~70 siblings.

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?

Beyond the annotations, the description explains pricing behavior: x402 USDC on Base or free with WICKEDAPI_API_KEY, and clarifies that an HTTP 402 response is a price quote rather than a failure. It also mentions read-only behavior and that timeframes match TradingView candles, adding useful context not covered by 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?

The description is front-loaded with the core resource and returned fields, then moves to an example, usage boundaries, and payment behavior. Every sentence contributes useful information without repetition or waste.

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, but the description enumerates the relevant return fields (CE, gap size, age, fill status, distance from price). With all parameters documented in the schema and pricing/usage behavior covered in the description, an agent has enough information to call 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 description coverage is 100%, so the schema already documents all six parameters in detail. The description only provides an example using symbol and timeframe, adding little semantic information beyond what the schema already provides.

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

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

The description names a specific resource (Fair Value Gap zones) and enumerates the exact data returned: CE, gap size, age, fill status, and distance from price. It also explicitly distinguishes itself from liquidity_levels, so an agent can tell what it does and what it does not do.

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 states when to use the tool ('when you want Fair Value Gap zones ... with fill status and distance from price') and when not to use it ('Not for swing-high/low liquidity pools'), naming the alternative sibling tool. This is explicit routing guidance with no inference required.

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, and destructiveHint=false, so safety is covered. The description adds valuable context: 'Free, no signup required' and 'no key or payment needed,' which are not in annotations. It also mentions the data source (Etherscan). It stops short of mentioning rate limits or data freshness, keeping it at a 4.

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 purpose, followed by a usage example, then explicit when-to-use/when-not, and finally a brief behavior note. Every sentence adds value with no 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?

For a simple, parameterless data retrieval tool with rich annotations and no output schema, the description covers what it does, when to use it, and key behavioral traits (free, no key). It is complete enough for an agent to call it correctly without further information.

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 zero parameters, the baseline is 4. The description does not need to explain any parameter semantics, and it correctly focuses on purpose and usage.

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 specifies the resource (Ethereum gas oracle), the data provided (safe/propose/fast gas prices + base fee, in gwei), and the source (Etherscan). It explicitly distinguishes from siblings by stating 'Not for other chains,' making it immediately clear this is not a general blockchain data tool.

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 explicit when-to-use guidance: 'Use when you need current Ethereum gas prices ... before sending a transaction.' It also states when not to use: 'Not for other chains.' This is clear and actionable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely non-derivable behavior: x402 USDC-on-Base pricing or free with an API key, and that an HTTP 402 carries a decoded price quote in payment_required rather than being a failure. It also warns the endpoint is not geo-blocked, which no annotation conveys.

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 payload fields, then example, then usage routing, then behavior — a sensible order with no filler. The opening field list and the 'Use when you need...' sentence partially restate the same content, which is the only 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?

For a single-parameter read tool with no output schema, the description covers return contents, auth/payment paths, the 402 edge case, and the sibling alternative. Nothing an agent needs to call it or interpret a non-200 response 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 a described required symbol field, so the baseline is 3; the description adds a concrete invocation example (`/v1/hyperliquid?symbol=BTC`) and the coin-name convention (BTC, ETH, SOL) that reinforces the schema's intent. It stops short of any edge-case handling for invalid symbols.

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 the specific resource (Hyperliquid perpetual context) and enumerates exactly what it returns: hourly funding, open interest, mark/oracle/mid price, premium, 24h volume. It explicitly separates itself from the sibling funding_oi by naming it as the tool for Binance/Bybit aggregates, so an agent can discriminate 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?

Gives an explicit when-to-use ('need Hyperliquid perp context') and an explicit when-not-to-use with the named alternative ('Not for Binance/Bybit aggregates (use funding_oi)'). This is the strongest form of routing guidance among the siblings.

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 flag readOnlyHint=false, idempotentHint=false, openWorldHint=true, and the description adds real value beyond that: the clock starts on return, the challenge is one-pass, and real-wallet vs sandbox credential requirements differ. Minor blemish: it says '30s budget' and then 'about 12 seconds to answer', which leaves the actual time constraint ambiguous. The trailing 'writes state upstream (not read-only)' largely restates the 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?

Front-loaded with the action and the clock constraint, and the wallet/sandbox split is clearly separated. It loses a point for redundancy: the closing 'Behavior: writes state upstream (not read-only); needs the credentials or wallet signature noted above where applicable' repeats the annotation and the credential info already stated in the first paragraph.

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 does step in by naming expires_at as a returned field and by describing the one-pass answer flow. Some return-shape detail (what the challenge itself looks like) is left implicit, but for a challenge-issuing tool the agent has enough to call it and to know what to do next.

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 genuine ordering semantics the schema cannot: for a real wallet you must fetch and sign the nonce for the next call BEFORE invoking this, and sandbox uses wallet + sandbox_token instead of nonce/signature. That cross-tool sequencing is the kind of meaning the schema descriptions only hint at.

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 ('Request a real time-boxed liveness challenge') and immediately characterizes the payload ('constrained-generation task'), so the agent knows what it is getting back in kind, not just name. It also names the sibling it is not (identity_register) and the follow-up (identity_submit_response), making it distinguishable 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 preconditions ('wallet is registered', fresh nonce fetched and signed before the call) and an explicit exclusion ('Not for registering first (use identity_register)'). The answer path via identity_submit_response before expires_at is spelled out, so the agent knows the next tool and the deadline.

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?

While annotations already show it is not read-only or idempotent, the description adds high-value behavioral context: the state is written upstream, it is single-use, and has a 5-minute TTL. This critical timing/state information is crucial for agent logic.

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 highly structured and avoids filler. While slightly verbose to include all contextual details, the information is front-loaded and clearly segmented, making it easy to parse for an AI.

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 definition is highly complete for a step-based flow tool, detailing its purpose, required input format (wallet context), and stateful, non-idempotent nature, which fully equips the agent to use 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?

Although the schema coverage is 100%, the description adds vital meaning by specifying that the input 'wallet' must be a '0x wallet address on Base' or a specific sandbox wallet ID. This guides the agent on the required format and environment context.

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

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

The description clearly states the tool's purpose as a prerequisite for signing or taking a challenge ('a one-time nonce + message to sign'). It effectively differentiates itself from sibling tools like identity_status, which is used for checking status.

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 provides explicit instructions on when to use the tool (register or take a challenge) and when explicitly *not* to use it (checking status), leaving no ambiguity for the agent.

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?

Adds meaningful behavior beyond annotations: 7-day expiry, 20 requests/min, 5 keys per IP per day, and that it writes state upstream rather than being read-only. The credential requirement phrase is somewhat vague, but the description is consistent with the annotations and discloses important limits.

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

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

The description is front-loaded with purpose and limits, and most sentences earn their place. The closing behavior sentence is slightly boilerplate and its 'noted above where applicable' phrasing is vague, but overall it remains readable and compact.

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 mutation tool with annotations present, the description covers the key missing context: expiry, rate limits, usage scope, and non-production status. It does not describe the returned key object, which is a minor gap given there is no output 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?

The input schema has 100% description coverage for the single optional label parameter, so the baseline is 3. The description does not add meaning about the label parameter beyond what the schema already provides.

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

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

States a specific verb and resource: getting a free self-serve test API key. It also distinguishes the use case from paying via x402 and names the sibling tool where the key is used, identity_status.

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 when to use it (testing the Identity API and wanting a free sandbox key) and when not to use it (not for production). It also names the alternative payment path via x402.

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/open-world, so the lower bar applies; the description still adds that the call is free and that sandbox=true returns a separate key set signing sandbox assertions (issuer wicked-identity-sandbox). It omits return shape (e.g. JWKS format), but the annotation set plus the added sandbox-key context is solid.

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 the sibling exclusion follows immediately. The trailing 'Behavior: read-only.' is redundant with readOnlyHint=true and slightly dilutes an otherwise tight description.

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-required-parameter read tool with full schema coverage and complete annotations, the description covers purpose, the sandbox parameter's meaning, and routing to the sibling. An agent has everything needed 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 description coverage is 100% and the single parameter is already documented in the schema. The description only mildly extends it by noting the sandbox key set signs sandbox assertions, so the baseline of 3 is appropriate.

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

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

States a specific verb+resource: returns public RS256 keys for local verification of an assertion_token, plus the sandbox variant. It also explicitly distinguishes itself from identity_status, so an agent can route 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 'Use when' condition (verifying an assertion token locally) and an explicit 'Not for' exclusion with the named alternative (identity_status for wallet status). Both the positive and negative routing signals 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=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful context beyond those annotations: it writes state upstream, requires a wallet signature over the nonce message, and this tool never signs on the user's behalf. It does not describe the response shape, but the safety/mutation profile is well covered.

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

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

The description is front-loaded with the action, prerequisites, and alternatives. It is slightly verbose with the bracketed prefix and a final behavior sentence that partially repeats annotation information, but every part is relevant and no major waste is present.

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 mutation tool with full schema coverage, rich annotations, and no output schema, the description gives enough operational context to call it correctly: prerequisites, non-signing behavior, alternatives, and upstream write behavior. It could be slightly more complete by noting what a successful registration returns or records, but that is 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?

Schema description coverage is 100%, and the schema documents wallet, nonce, and signature with formats. The description reinforces that the nonce should come from a fresh identity_get_nonce call and that the signature is over that nonce's message, but this largely repeats schema-level meaning. Baseline 3 is appropriate when the schema carries 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 states a specific verb and resource: register a REAL wallet as an identity. It explicitly distinguishes this from sandbox registration and from agent-challenge proving, so an agent can select it without opening sibling 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?

It gives explicit when-to-use guidance ('lightweight identity record for your wallet') and names alternatives: sandbox identities use identity_sandbox_register, and proving agent status uses identity_get_challenge. The prerequisite path through identity_get_nonce is also stated.

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?

Beyond the annotations, the description adds genuinely useful operational context: a rate limit of 10 per IP per hour, the fact that results are signed with a separate key (identity_jwks sandbox=true), and the warning that sandbox identities are never reported as verified. The closing 'Behavior: writes state upstream (not read-only)' sentence largely restates readOnlyHint=false, so it adds little, but the surrounding context is substantive.

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 front-loaded with the 'START HERE' cue and the follow-up chain appears in the first two sentences. Some content is duplicated, though: 'Use a real wallet for an accountable identity' repeats the point already made in 'never reported as verified' and again in 'Not for production verification', and the 'Behavior:' line restates annotations.

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 tool with no output schema, the description fully covers what comes back (sandbox wallet plus sandbox_token), what to do next, the rate limit, and the safety caveat about sandbox keys. An agent has everything it needs to call this correctly and interpret the result.

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 the baseline is 4 and there is no parameter semantics to explain. The description appropriately spends its words on outputs and follow-up steps instead of inventing input details.

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 and its unique scope: it registers a sandbox identity and returns a sandbox wallet plus a sandbox_token, with no signing or request body needed. It also implicitly separates this tool from identity_register by pointing to real wallets for accountable identities, so an agent can choose between the two 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 an explicit trigger ('Use when you have no wallet and want a sandbox identity to test the flow'), an explicit exclusion ('Not for production verification, which needs a real wallet signature'), and names the follow-up tools to call (identity_get_challenge, identity_submit_response). Nothing about when or when not to use this tool is left 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 only say read-only/idempotent/open-world; the description adds materially new facts: no signature is required, the call is paid via x402 unless an api_key is supplied (with two acquisition paths), and sandbox wallets are never reported as verified. These are auth, cost, and result-semantics details an agent cannot get from annotations.

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

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

The core question is front-loaded and the payment/auth caveat is compactly bundled into one sentence. A little density remains in the x402/api_key clause, but 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?

With no output schema, the description still signals what the response looks like by naming the verified / sandbox / sandbox_verified fields, which is enough for an agent to interpret results. A brief note on non-verified failure modes (e.g. expired vs never-issued) is the only real omission.

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 wallet and api_key are already documented in the schema. The description only restates the api_key sourcing hint and does not add format or validation semantics beyond that. Baseline 3 is appropriate when 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?

Opens with a precise question form of a specific verb+resource: whether a wallet currently holds a valid, unexpired assertion. It is immediately distinguishable from identity_get_nonce and identity_register, which are named or implied as the verification path.

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 triggering condition ("Use when you want to know whether a wallet currently holds a valid, unexpired agent assertion") and an exclusion with a redirect ("Not for becoming verified (start with identity_get_nonce)"). That is the full when/when-not/alternative triad.

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

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

Annotations cover readOnly=false and openWorld=true; the description adds that it writes state upstream, that a pass returns a short-lived signed JWT, and that real wallets need a DIFFERENT fresh nonce than the one identity_get_challenge used. Missing: what a fail/inconclusive response looks like, retry semantics, or nonce-reuse failure behavior, so not 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?

Front-loaded with the core action and outcome, then mode/credential requirements, then usage routing. The '[Wicked Identity]' prefix and the piped mode separators are slightly dense but every clause carries real information; nothing 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 6-param, non-idempotent, open-world mutation with no output schema, the description supplies what's needed to call it correctly: required credentials per mode, the fresh-nonce constraint, and what a pass returns. It stops short of describing failure-path returns or error behavior, so not 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 coverage is 100%, so the baseline is 3; the description adds genuine cross-parameter semantics the schema can't express: the real-wallet vs sandbox mode split (nonce+signature vs sandbox_token) and the crucial constraint that the nonce must be fresh, not the get_challenge nonce. It doesn't restate challenge_id or response_text, which the schema already covers.

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: submit an answer to a challenge, scored pass/fail/inconclusive. It also names what a pass yields (a short-lived signed assertion_token JWT verifiable via identity_jwks), which distinguishes it sharply from siblings like identity_get_challenge and identity_jwks.

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 'Use when you have the challenge answer and want it scored' plus an exclusion: 'Not for getting the challenge (use identity_get_challenge).' It also names the prerequisite steps (identity_get_nonce for real wallets, identity_sandbox_register for sandbox), so the agent knows the call sequence.

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/openWorld/idempotent/non-destructive, yet the description adds genuinely new behavior: payment via x402 (USDC on Base) or WICKEDAPI_API_KEY, and that a 402 with decoded price is a quote, not a failure — a critical non-obvious detail. It stops short of describing the response shape beyond a high-level mention of orderbook/trades.

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 resource and example, then usage and payment caveats in a scannable structure. Slightly padded by the markdown formatting and an example URL that duplicates the schema's ticker example, but every section carries real information.

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

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

For a read-only 3-param tool with no output schema, the definition covers what it returns at a high level (orderbook yes/no levels, recent trades), the usage boundary, and the payment-failure semantics that would otherwise confuse an agent. Full completeness would require a bit more on the returned structure, but the essentials 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 coverage is 100%, so ticker format, depth default/max, and trades default/max are already documented in the schema. The description only reinforces the ticker example already present in the schema, adding no new syntax or 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 (fetch) and resource (single Kalshi market depth: orderbook + recent trades) scoped by ticker, and explicitly names the sibling it differs from (kalshi_probability). An agent can distinguish it from the browsing tool 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?

Gives an explicit when-to-use line ("when you need one Kalshi market's orderbook and recent trades by ticker") and an explicit when-not with the alternative tool named ("Not for browsing markets by category (use kalshi_probability)"). Prerequisites are also covered via the ticker example.

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 the safety profile is covered. The description adds non-annotation context: free, no signup, no key or payment, and that a category query returns the most active open markets. It stops short of describing pagination or the shape of the returned probability data, which keeps it off 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?

Front-loaded purpose, then example, then routing guidance, then behavior — each sentence earns its place. No filler, and the exclusions are placed before the behavioral footnote where an agent will actually read them.

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 public data tool with full schema coverage and no output schema, the description covers purpose, routing, cost and the one return-value nuance that matters (most active open markets). The remaining gap is that nothing tells the agent what the probability payload looks like or about the category-required schema quirk.

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 meaning beyond the schema: it explains the semantics of a category query (returns the most active open markets rather than an arbitrary slice) and gives a worked example URL. It does not resolve the schema's internal conflict where 'category' is listed as required while its own description says category OR ticker is required.

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 concrete verb+resource ("Kalshi prediction-market probabilities") plus the two query modes (category or ticker), and explicitly names the sibling tools it is not (kalshi_market, polymarket). An agent can distinguish it from all ~80 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?

Explicit when-to-use ("Use when you want live Kalshi prediction-market probabilities by category or ticker") plus two named exclusions with the correct alternative for each (kalshi_market for single-market depth, polymarket for Polymarket). That is the full when/when-not/alternatives 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 read-only safety, but the description adds non-obvious behavior: real exchange data with no estimates, and the payment/auth model (x402 USDC on Base, free with WICKEDAPI_API_KEY, otherwise HTTP 402 with a decoded price in payment_required that is a quote, not a failure). That last point prevents an agent from misreading a 402 as an error.

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 capability, then example, then when-to-use, then behavior — a sensible order. Slightly long because the paywall sentence is dense, but every element carries 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?

Covers scope, defaults, return fields, the sibling alternative, and the non-standard failure mode. With no output schema, the description compensates by naming the returned fields and aggregates rather than relying on undocumented structure.

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 schema already documents both params including defaults and the 1-100 limit range. The description only restates 'for a coin' and shows an example URL; it adds no syntax or edge-case meaning 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+resource (recent forced liquidations) with scoping detail (OKX USDT perpetual swaps, per coin) and enumerates the returned fields, so an agent knows exactly what it gets.

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 when to use it ('when you want recent forced liquidations on OKX USDT perpetuals for a coin, with side and size') and names a disqualifying alternative — 'Not for liquidity pools (use liquidity_levels).'

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, openWorld), so the description rightly spends its words elsewhere: it discloses the pricing model (x402 USDC on Base or WICKEDAPI_API_KEY) and pre-empts the biggest agent trap by explaining that HTTP 402 with a decoded price is a quote, not a failure. That is behavior an agent cannot infer from 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?

Front-loaded one-line definition, then example, then when-to-use exclusions, then behavior/payment. Every sentence carries new information and nothing is repeated from the schema.

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 what the response contains (buy-side/sell-side levels, swept status, equal pools, nearest untaken targets) and by describing the non-200 payment path. For a six-parameter read-only data endpoint that is sufficient 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 schema already documents symbol, lookback, timeframe, swing_length, include_swept and equal_threshold_pct; baseline would be 3. The description adds modest semantic grounding by tying 'sweep/taken status' and 'relative-equal pools' to the corresponding parameters and by showing a concrete query (`?symbol=TQQQ&timeframe=1h`), though it does not explain units or defaults for the numeric knobs.

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 the resource (ICT buy-side liquidity above swing highs, sell-side below swing lows) and the specific data returned (sweep/taken status, relative-equal pools, nearest untaken targets). It also names the two closest siblings it is not (fvg, liquidations), so an agent can distinguish it 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?

Usage is explicit: 'Use when you want buy-side/sell-side liquidity levels and whether they were swept', followed by exclusions routing to named alternatives ('Not for gap zones (use fvg) or actual liquidation events (use liquidations)'). This is the when/when-not/alternative pattern in full.

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/safe semantics, and the description adds non-obvious context: paid via x402 or an API key, and that an HTTP 402 carries a price quote rather than being a failure. That pricing/auth disclosure is exactly the kind of behavioral info 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?

Front-loaded with the resource list, then example, usage, and behavior. The 'Use when...' sentence partially restates the opening enumeration, a minor redundancy, but overall it is tight and scannable.

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, but the description names the four ratio families returned and covers payment/auth behavior and an example call, which is sufficient for correct invocation. Return shape/pagination specifics are the only 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?

Schema coverage is 100% with each parameter described (symbol mapping to <SYMBOL>USDT, period enum). The description echoes usage only through the example query string and adds little parameter detail beyond the schema, 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+resource (Binance long/short ratios) and enumerates the four sub-metrics it returns, immediately distinguishing it from siblings. An agent can identify its function 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?

Explicitly says when to use it ('Use when you want Binance positioning ratios') and when not to ('Not for funding or open interest (use funding_oi)'), naming the alternative tool. Routing is unambiguous.

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

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

Annotations already cover readOnlyHint, idempotentHint, and non-destructive; the description adds non-structured context that it is free, requires no key or signup, and that dates are verified against Fed/BLS sources. It does not mention rate limits, pagination, or the response envelope, so it falls short of 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?

Purpose, data contents, and the sibling exclusion are front-loaded and earned. The raw endpoint example (`/v1/macro-calendar`) and the repeated free/no-signup phrasing in both the header and the Behavior line are mild 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 the needed work by enumerating what comes back (dates, days-until, cut/hold/hike odds) and confirming no auth is needed. Pagination and response size limits are unstated, which is a minor gap for a calendar-style list tool.

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 parameters (days, type) are already documented in the schema. The description only indirectly clarifies that type values map to FOMC/CPI/jobs (NFP) and adds no format or boundary detail beyond that, 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: returns upcoming US macro events (FOMC, CPI, jobs report) with verified Fed/BLS dates, days-until, and Kalshi odds. It also explicitly distinguishes itself from the closest sibling by naming earnings_calendar as the wrong tool for company events.

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 positive trigger ("Use when you want upcoming US macro events... with verified dates") and an explicit exclusion with the alternative to use instead ("Not for company earnings (use earnings_calendar)"). An agent has a complete routing rule.

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, openWorldHint), and the description adds materially new behavioral facts beyond them: payment via x402 (USDC on Base) or free with WICKEDAPI_API_KEY, and crucially that an HTTP 402 response carries the decoded price in payment_required and is a quote, not a failure. That last point prevents an agent from misinterpreting a normal response as an error.

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

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

Front-loaded with purpose in the first sentence, then example endpoint, usage rule, and behavior — a clean, scannable structure. It loses a point for redundancy: "Crypto endpoints are 24/7 and unaffected" and "Not for crypto, which trades 24/7" say the same thing twice.

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 still names the key return fields (is_open, next_open/close) and explains the non-obvious 402 payment flow, which is enough for correct invocation. It does not describe the shape of the upcoming-sessions list or pagination/limits, a minor gap for a single-parameter read tool.

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 `days` parameter is fully documented in the schema (default 3, max 30, 0 to omit). The description only implies that upcoming sessions are configurable via "+ upcoming sessions" and adds no syntax or default 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+resource: returns the US equities market clock (is_open, next_open/close) plus upcoming sessions, sourced via Alpaca. It explicitly bounds scope to US equities and declares crypto out of scope, so an agent can distinguish it from the other 24/7 crypto price/OHLCV tools in the sibling list.

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 when you need to know whether US equity markets are open and when the next session opens or closes" gives the positive selection condition, and "Not for crypto, which trades 24/7" gives the exclusion. Both directions are stated explicitly rather than left 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 read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond annotations: it is free, requires no signup, and needs no key or payment. It does not describe rate limits or response format, so it falls short of 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 description is front-loaded and appropriately sized. It repeats the same stat list in the opening sentence and the 'Use when' sentence, which is a minor 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?

For a simple two-parameter read-only tool with full schema coverage and annotations, the description provides enough context: data source, use case, exclusion, auth/payment behavior, and the returned stat categories. Nothing essential for correct invocation 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 parameter documentation is already handled by the schema. The description implies the two views but does not add parameter names, defaults, or constraints beyond what the schema provides.

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

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

The description clearly states the resource and scope: CoinGecko global crypto stats or top coins by market cap. It explicitly distinguishes itself from the `price` sibling for single-asset queries, so an agent can select it 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 gives an explicit use case (global crypto stats such as market cap, volume, and dominance) and an explicit exclusion with the alternative: 'Not for a single asset's price (use price).' This leaves little ambiguity.

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 non-idempotent behavior, but the description adds material context: deletion is irreversible, an audit row without content is retained, default chain scope removes every version, and intent should be confirmed before calling. This is exactly the extra behavioral information an agent needs for a destructive operation.

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 destructive action and scope behavior, then gives usage routing and a safety warning. There is some repetition around permanence and destructiveness, but for a high-risk deletion tool the redundancy is defensible rather than wasteful.

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 annotations and fully described schema, the description supplies the missing behavioral context: irreversibility, audit retention, scope consequences, and a confirmation warning. No output schema exists, but the key outcome (audit row retained, content deleted) is stated.

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 parameter documentation is already strong and the baseline would be 3. The description adds consequence-level meaning for the scope parameter by explaining that default chain scope removes every version while version scope removes only one, which is useful beyond the schema's brief scope note.

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: permanently hard-delete a memory. It also specifies scope behavior (chain vs version) and explicitly distinguishes this from memory_update, so the agent can identify it among memory 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?

Gives an explicit when-to-use condition (permanent erasure / right to be forgotten) and a clear when-not-to-use alternative (correcting a memory should use memory_update). The routing guidance is unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so "Behavior: read-only" is largely redundant. The valuable addition is the irreversibility note ("content is gone", "never content"), but the wallet/nonce/signature auth flow — the real behavioral gotcha for calling this — is left entirely to 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?

The core information is front-loaded, but the second sentence restates the first almost verbatim ('audit log of deletions (ids, times, reasons, never content)'), which is wasted space in a three-sentence description. The exclusion clause earns its place; the duplication does not.

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, non-destructive query with no output schema, the description tells the agent what fields come back and that content cannot be recovered, which is enough to call it correctly. Only the memory_prepare prerequisite chain is unmentioned in prose, though the schema covers 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 description coverage is 100% and all four parameters (wallet, timestamp, nonce, signature) are documented in the schema itself, including the dependency on memory_prepare. The description adds no parameter-level meaning, which is acceptable given the schema baseline of 3.

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 resource (a deletion audit log) and enumerates its contents (ids, times, reasons, never content), so the agent knows exactly what this returns. It stops short of differentiating itself from the closely named sibling memory_history or from memory_delete, which leaves room for confusion among the memory_* family.

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 when you want your audit log of deletions" gives an explicit trigger, and "Not for recovering content, which is gone" gives an explicit exclusion plus the reason. It does not name sibling alternatives (e.g., memory_history for non-deletion events), so it falls just 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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful non-obvious behavior: another wallet's memory or a deleted id returns the same 404. It repeats 'read-only' but does not contradict annotations.

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

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

The description is short, front-loaded with the core action, and structured into purpose, usage guidance, and behavior. Every sentence contributes to selecting or understanding the tool.

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

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

The tool is simple and the annotations plus schema are rich, while the description adds the important 404 behavior and sibling routing. Since there is no output schema, it could say more about the returned memory shape, but overall it is adequately complete for calling 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 description coverage is 100%, so all five parameters are already documented in the schema, including memory_id, wallet, nonce, timestamp, and signature. The description mentions the memory id conceptually but adds no parameter-level syntax or constraints 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: 'Fetch one of your memories by id.' It also distinguishes this tool from memory_search by clarifying that it is not for semantic search.

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 usage condition ('when you have a memory id and want its content') and an explicit alternative ('Not for searching by meaning (use memory_search)'). No inference is needed to choose between memory_get and memory_search.

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 useful behavioral detail beyond annotations: ordering is oldest first, the chain includes valid_from / valid_until / superseded_by, and any version id can be used as the starting point.

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 short and front-loads the return shape and usage guidance. The final 'Behavior: read-only' sentence repeats what annotations already declare, so it is slightly redundant, but the overall structure remains efficient.

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 the work of explaining the returned fields and ordering, which is important for this tool. The authentication parameters are covered by the schema, so the definition is nearly complete, though it could mention whether the chain is paginated or always full.

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, including that memory_id is a UUID of any version in the chain. The description reinforces this but does not add meaning beyond what the schema provides.

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

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

States a specific resource and operation: the full version chain for a memory, oldest first, with validity fields. It also distinguishes itself from memory_get by scoping the tool to historical versions rather than current content.

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 to use it (full version chain and validity windows) and when not to use it (current content, directing the agent to memory_get). This gives a clear routing decision between siblings.

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, and the description adds traits annotations cannot express: pure local computation, no network call, nothing is stored, timestamp must be within 5 minutes, and the nonce is single-use. Those are exactly the operational constraints an agent must know before composing a signed call.

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 sections (what it returns, when to use, behavior) with the returned value front-loaded. No filler sentences; each one carries a constraint or routing instruction.

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 3-param prerequisite tool with no output schema, the description still names the returned field (`message_to_sign`) and the full two-step signing workflow. An agent has everything needed to call it correctly on the first attempt.

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 nevertheless adds the non-obvious coupling that `params` must be the SAME arguments later passed to the target memory_* tool, and that the returned timestamp/nonce/signature travel alongside them. It does not enumerate the operation strings beyond what the schema already lists.

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 returns the exact `message_to_sign` for a Wicked Memory operation. It explicitly positions itself against siblings by saying it is for the signing step and 'Not for the call itself', so an agent can distinguish it from memory_store, memory_get, etc. 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 the precise when: before calling any other memory tool, then sign with EIP-191 personal_sign and call the matching memory_* tool with the SAME arguments plus timestamp, nonce and signature. It also names the exclusion ('Not for the call itself') and the re-use rule (nonce is single-use, so prepare again for every call).

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 annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false. The description adds substantive behavioral context beyond annotations: it is a metered call, free with MEMORY_API_KEY, otherwise returns HTTP 402 with x402 v2 payment instructions, costs 0.001 USDC on Base, and requires retrying with the SAME arguments plus payment_signature. This is exactly the kind of operational detail 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?

The description is front-loaded with purpose and usage guidance, then gives necessary payment details. It is generally efficient, though the final 'Behavior: read-only.' sentence merely repeats the readOnlyHint annotation and 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 complex 12-parameter tool with payment flow and no output schema, the description covers purpose, usage, payment/retry behavior, and read-only nature well. It does not describe the shape of returned results, which is a minor gap given the absence of an output schema, but an agent has enough to invoke 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 description coverage is 100%, so the schema already documents all 12 parameters, including q, tags, as_of, limit, nonce, wallet, signature, timestamp, and payment_signature. The description adds some useful parameter-usage context via the retry rule and payment_signature flow, but it does not elaborate on the individual search filters. 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: 'Semantic search over YOUR memories only, ranked by real cosine similarity.' It also distinguishes from the sibling memory_get by saying it is not for fetching a known id. An agent can clearly identify what the tool does and how it differs from related tools.

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

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

Explicitly says when to use it: 'Use when you want to recall your memories by meaning rather than by id.' It also names the exclusion and alternative: 'Not for fetching a known id (use memory_get).' This leaves no ambiguity about tool selection.

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=false, and openWorldHint=true, so the "writes state upstream (not read-only)" sentence largely restates them. The description does add genuine non-annotation context: free/fair-use rate limiting, embedding computation at write time, wallet signature requirement, and the single-use nonce flow that makes retries unsafe.

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

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

Front-loaded with purpose, then prerequisite, then exclusion, then behavior — good ordering with no wasted preamble. The closing line "needs the credentials or wallet signature noted above where applicable" is generic boilerplate that mostly echoes the annotations, keeping it off a 5.

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

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

For an 8-parameter signed write with full schema coverage and annotations, the description covers the prerequisite flow, rate-limit posture, and mutation semantics. It stops short of saying what comes back (memory id, embedding reference) or whether stored tags/metadata are indexed for later memory_search, which is a minor gap given no output 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 per-parameter meaning is already documented; baseline would be 3. The description earns above baseline by explaining that the wallet scopes the write and that the nonce/timestamp/signature trio must come from a prior memory_prepare call with identical arguments, which is a cross-field relationship the schema does not express.

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?

"Store a memory" is a specific verb+resource, and the description immediately scopes it ("scoped to your wallet") and names the sibling it is not ("Not for changing an existing memory (use memory_update)"). An agent can distinguish this from memory_update, memory_search, and memory_prepare 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 when-to-use ("save something for later, scoped to your wallet"), explicit when-not plus the alternative ("Not for changing an existing memory (use memory_update)"), and a stated prerequisite flow ("Run memory_prepare with operation 'store' and these same arguments first"). All three routing signals an agent needs 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 flag readOnlyHint=false, non-idempotent and non-destructive; the description goes well past them by disclosing the versioning model, that omitted fields carry over, and that only the current version is updatable (409 otherwise) — a concrete failure mode an agent must anticipate. It also flags the wallet/signature auth requirement, though 'noted above where applicable' is a dangling reference to context not present in this record.

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 key mechanic, then usage, then behavior — three tight blocks with no redundancy. The final sentence's 'noted above where applicable' is filler that points at nothing and could be cut or replaced with the actual auth requirement.

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 9-parameter, non-idempotent write with no output schema, the description covers the semantics that matter: versioning, partial-update behavior, auth, and the 409 failure case. It stops short of saying what the response contains (e.g. the new version's id), which is the main remaining 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 would be 3, but 'Omitted fields carry over' resolves a real ambiguity created by schema wording like 'Replacement tags' and 'Replacement metadata object' — it tells the agent this is a partial update, not a whitelist replacement. The memory_id wording ('CURRENT version to supersede') is reinforced by the description's 409 rule.

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 plus the non-obvious mechanics: creating a new version and closing the old one via valid_until / superseded_by. It also explicitly contrasts itself with memory_delete, so an agent can separate it from the delete sibling 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?

'Use when you want to change a memory while keeping its history' gives the positive trigger, and 'Not for removing it (use memory_delete)' gives both the exclusion and the named alternative. The 409-only-current-version constraint further bounds when the call will succeed.

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/non-destructive, and the description adds genuinely non-obvious context: pricing via x402 (USDC on Base) or an API key, and that a bare HTTP 402 carries a price quote rather than being a failure. That last point is a real operational trap avoided. Slight deduction because it doesn't say whether the oracle pipeline can go stale or fail independently.

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 identity and payload, then example, usage, and behavior. Mostly tight, but 'Alias of /v1/verdict' and 'Same data as verdict, which is the newer name' are redundant statements of the same fact.

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 enumerating the returned fields (bias, confidence, thesis, entry/invalidation/targets, signal readings). It also covers the payment/discovery path and the 10-asset boundary, leaving nothing an agent needs 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% (symbol enum and timeframe values fully documented in-schema), so the schema carries the semantics. The description reinforces the 10-asset scope and shows a sample query string, but adds no format or default detail beyond what the schema already provides.

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

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

States the concrete resource (multi-asset momentum verdict) and enumerates its payload (bias, confidence, thesis, entry/invalidation/targets, signal readings), plus the source pipeline and 10-asset scope. It also explicitly positions itself against siblings: it is the same data as verdict (the newer name) and is not for raw inputs like price/atr/funding_oi.

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-to-use ('ready-made LONG/SHORT/NEUTRAL view with confidence, thesis and entry/invalidation/targets') and an explicit when-not ('Not for raw inputs') naming the three alternative tools. It also flags that verdict is the newer name for the same data, which is exactly the routing decision an agent needs.

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