Insight MCP

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

With no annotations, the description carries the full burden and does substantial work: it lists returned artifacts (preTradeUid, requestHash, CAIP-19 asset ids, certified cross-rate, 50 bps band, verdicts, signed attestations), flags deprecation and a hard removal date, and warns that the handle is not authorization. It stops short of auth requirements, handle expiry/idempotency, and failure behavior beyond what the schema mentions.

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 exclusions, then return shape, then deprecation routing — a sensible priority order. Every sentence carries distinct information (trigger, prohibition, outputs, migration), with no filler.

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

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

For a 10-parameter, 7-required nested-object tool with no output schema, the description covers purpose, prohibitions, return payload, chain support caveat, and deprecation adequately. Gaps remain around input field intent (providers, protocol_id, decision_input usage) and operational concerns like auth or handle lifetime.

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?

At 50% schema coverage across 10 parameters, the description should compensate but barely touches inputs. The only input-adjacent detail is the '50 bps band', which merely restates the schema's const 50; undocumented parameters like providers, protocol_id, source_group_count, and the action enum get no explanation, and the long return-value list does not help an agent fill the input.

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 framing: 'Open the verifiable execution loop: certify a swap/DeFi intent before the agent executes.' It also distinguishes itself from the sibling trade_proof by naming the exact replacement call (op "begin_evidence") and giving a removal date, so an agent can route correctly 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?

Explicitly states the trigger condition ('when a principal needs a signed pre-trade handle to bind an execution receipt later') and two negative cases ('Do not use it as trade authorization', 'do not call it after the trade'). It also names the preferred alternative, so when-to-use, when-not-to-use, and the substitute are all covered.

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

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

With no annotations supplied, the description carries the full burden and does add real value: it discloses the verdict taxonomy (PASS/CAUTION/DANGER/BLOCK), reason codes, oracle evidence, optional signed attestation, and a deprecation/removal date of 2027-01-06. It does not disclose cost, latency, failure modes when evidence is stale or unavailable, or who can verify the attestation, which are material for a gating tool with no readOnly/destructive hints.

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

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

Four tight sentences, front-loaded with the action and scope, then usage timing, then return values, then migration. Every sentence carries information, though the deprecation sentence sits at the end where a high-volume caller might miss a removal date that would ideally be surfaced earlier.

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

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

The description compensates for the missing output schema by enumerating the return payload, and correctly documents the deprecation path. For a 32-parameter, nested-object tool spanning five venue families, however, the absence of any parameter-by-action mapping leaves a substantial gap that neither the schema (56% coverage) nor the description closes.

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 the `guard` parameter gets added meaning ('pass the family native payload here when the venue needs exact-call fields'). Against 32 parameters at 56% schema coverage, there is no guidance on which parameters pair with which `action` value (e.g. borrows/collaterals for borrow, position for check_position, market/side for perps) — the single most important thing an agent needs to construct a valid call.

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 ('Run the pre-trade oracle safety gate') and enumerates the covered domains (swaps, lending, perps, vault deposits, stress tests) and chains (Base, Monad, multichain EVM, Solana, Hyperliquid). It also distinguishes itself from siblings by naming trade_proof for post-execution and trade_guard as the preferred successor.

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 timing ('immediately before an agent trades or signs'), an explicit anti-pattern ('Do not use it after execution (use trade_proof)'), a scope caveat ('do not treat its PASS as principal authorization'), and a migration instruction pointing at trade_guard with op "check_safety". Nothing about when to select 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?

With no annotations, the description carries the full burden and does well: it marks the operation as a read, scopes it to a reviewed allowlist of venues, states it is not an authorization signal, and discloses the deprecation plus removal date. It stops short of noting permission prerequisites or rate limits, 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?

Four sentences, front-loaded with purpose, then usage, then exclusions, then return shape, then the deprecation notice. Every sentence contributes, though the deprecation sentence could arguably lead or be trimmed given its verbosity.

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 compensates by naming what is returned (market record, reviewed profile ids, current quote context). Combined with explicit scope limits and the migration path to trade_guard, an agent has enough to call it correctly; only auth and error behavior are 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?

Schema description coverage is 100% with two enumerated parameters, so the schema already explains venue, market, venues and profile_id. The description only echoes the concepts ('venue constraints', 'market id') without adding format, interaction or conditional rules (e.g. when market vs venues applies). Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Read one reviewed venue market') and enumerates what is returned: pool/market metadata, pinned quote context and venue constraints across four named chains. It also identifies itself as a deprecated alias for trade_guard op "market_quote", so an agent can distinguish it from the sibling that supersedes it.

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 exactly when to call it ('before preparing or gating a trade when the agent needs the reviewed profile or market id'), when not to ('not as execution authorization', 'not for prices outside the reviewed venues'), and names the preferred alternative (trade_guard with op "market_quote"), including a removal date.

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?

With zero annotations the description carries the full burden, and it does disclose the return shape ("requested analysis rows plus provider participation and reference prices") and lifecycle status (deprecated, removed 2027-01-06). It says nothing about permissions, rate limits, cost, or what happens on partial provider failure, which matters for a fan-out analytics 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?

Front-loaded with the core action and scoping, and the deprecation notice is short and unmissable. The opening enumeration of analysis types partly duplicates the schema's mode and metric enums, so a little of it is redundant rather than additive.

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 13-parameter, multi-mode tool with no output schema, the description covers purpose, routing, return values, and deprecation adequately, with the schema handling parameter detail. The only real gap is failure and permission behavior across multiple providers, which is left entirely implicit.

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 92%, so the baseline is 3 and the description does not beat it: it restates mode/metric value families without explaining precedence rules such as metric overriding mode or consensus/risk/history only using the first asset. Those rules live in the schema, so no value is added beyond it.

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?

"Run multi-oracle price analytics" gives a specific verb plus resource, and the following clause enumerates the concrete analysis families (consensus, batch, history, spreads, deviation, correlation, risk). It also names the siblings it is not (get_oracle_price, get_oracle_health), so an agent can route without opening any schema.

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

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

Explicit positive condition ("when one price is not enough and the caller needs to compare, stress or trend oracle data") plus explicit exclusions naming the two better-suited siblings. It goes further and names trade_guard with op "price_analytics" as the preferred path, with a hard removal date, 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.

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

With no annotations, the description carries the full burden, and it does well: it discloses the returned verdict vocabulary (FAITHFUL/DEVIATED/NOT_EXECUTED/UNDETERMINED), price delta, binding ids, and a verify URL, plus a deprecation/removal date. It does not cover authorization requirements, idempotency of re-issuance, or rate limits, which keeps it below a 5.

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

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

The core action and the post-settlement precondition are front-loaded, and most sentences carry real information. The deprecation and removal-date sentence plus the return-value enumeration make it dense as a single unbroken block, but little is genuinely 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 five-parameter, mode-switched mutation tool with nested objects and no output schema, the description supplies the return shape and the critical timing constraint that the schema cannot express. Gaps remain around mode selection guidance and any permission prerequisites, but nothing essential for a 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 60%, so the schema already explains the receipt and decision objects and the Solana signature. The description adds conceptual mapping ('pre-trade handle plus the settlement transaction') but never explains the mode enum values or the swap_tx_hash parameter, which has no schema description at all.

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 specific verbs and resources: issuing a signed execution-price receipt from a pre-trade handle plus settlement transaction, and settling a guarded Base/Solana swap. It explicitly distinguishes itself from the sibling trade_proof, calling itself a deprecated alias and pointing to trade_proof with op "issue_receipt", so an agent can route 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 precondition ('Use it only after the trade settled'), an explicit exclusion ('Do not use it before execution'), a semantic caution ('do not treat the verdict as principal authorization'), and a named alternative (trade_proof). All three of when, when-not, and alternatives 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?

No annotations are supplied, so the description carries the full behavioral burden and does so: it discloses that the oww_ token is one-time, that tokens are invalid after close, and that begin costs 500 credits / $0.500 while in-window poll and close are free and snapshot/history are 20 credits. It also notes which deprecated tool names are absorbed, which matters for an agent choosing among near-identical siblings.

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

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

The purpose and the branching model are front-loaded in the first two sentences, and the prohibitions and metering follow in a logical order. It is dense but nearly every clause carries distinct information; the metering sentence is long but genuinely decision-relevant for a paid call.

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 7-parameter, 5-branch tool with no output schema, the description covers return values per branch (signal/series, windowId plus token and expiry, poll signal or close summary), costs, and token lifecycle. The remaining gap is the un-explained optional parameters (days, interval, window_id) that determine history and window behavior.

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 only 43%, and the description compensates for the hardest part by explaining what each op value means and where windowId and the oww_ token come from. However, it adds no meaning for days, interval, or window_id beyond the schema, leaving several low-coverage parameters undocumented in either place.

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 (Oracle Watch trust signals) and enumerates the five branches it multiplexes: snapshot, history, begin, poll, close. It also explicitly distinguishes itself from the sibling trade_guard (op check_safety), so an agent can tell the two apart 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 explicit when-to-use (read one snapshot or history series, buy a 24h window, poll/close a purchased window) and explicit when-not-to-use (pre-trade safety belongs to trade_guard). It also states two hard constraints: do not buy a second window for the same subject and never reuse a token after close.

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?

With no annotations, the description carries the full burden and does substantial work: it discloses that the token is one-time and must not be shared, that calling repeatedly for the same window is discouraged, what fields come back (windowId, oww_ token, covered expiry, credits charged), and a removal date. It stops short of stating cost magnitude, auth/permission requirements, or what error occurs on a duplicate begin 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?

Four short sentences, front-loaded with the action and its return value, then usage, cautions, and deprecation. No filler and no repetition of schema content; each sentence 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 two-parameter, no-output-schema purchase tool, the description covers purpose, when to use, return fields, token hygiene, and lifecycle/deprecation. The remaining gap is that it doesn't quantify charges or describe failure on a repeated call, which matters for a paid mutation with no annotations.

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 (symbol, chain) are already documented, and the description adds only the loose notion of 'one asset' without clarifying symbol format or the chain filter's behavior. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource with scope: 'Buy a 24h Oracle Watch window for one asset and return the one-time control token.' It also explicitly contrasts with the per-snapshot sibling (oracle_watch) and names the preferred replacement tool, so an agent can distinguish it 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 an explicit positive condition ('when an agent will poll throughout a window instead of paying per snapshot'), an explicit exclusion ('Do not use it repeatedly for the same window'), a token-handling caution, and a migration path ('prefer oracle_watch_window with op "begin"'). Alternative selection 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?

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses the cost profile (poll costs zero extra credits), the differing return shapes for each op, one-time token semantics, and a deprecation timeline with a removal date. It stops short of describing what happens on a rejected or reused token and whether close is idempotent, which are the remaining behavioral gaps.

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 tightly packed with routing, cost, and deprecation facts. The final sentence ('Returns the signal (poll) or the combined summary (close)') largely restates the second sentence, which is the one piece of avoidable 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?

There is no output schema, and the description compensates by explaining what each op returns. Combined with the deprecation warning and preferred replacement, an agent has everything needed to call this correctly and to plan its migration.

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 67% and the schema already documents op's two values and the window_token's oww_ prefix. The description adds meaning the schema lacks: the token is one-time, comes from oracle_watch_window_begin, and must not be reused after close. window_id itself is still left to inference, but its meaning is unambiguous from 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?

States specific verbs (poll, close) applied to a specific resource (an already purchased Oracle Watch window) and names the token that scopes the operation. It explicitly differentiates itself from oracle_watch_window_begin (source of the token) and oracle_watch (one-off snapshot), so an agent can select it 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 an explicit when-to-use rule ('only with a window token from oracle_watch_window_begin'), an explicit when-not ('Do not use it for a one-off snapshot'), a lifecycle constraint ('never reuse a token after close'), and a preferred alternative (oracle_watch_window with op "poll"). Every routing decision is stated rather than inferred.

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?

With no annotations, the description carries the full burden and does well: it discloses the one-time plc_ token and expiry, the per-op return values, the token's invalidation after close, and that it absorbs the deprecated position_lifecycle_begin/position_lifecycle_step names. It stops short of stating cost/payment mechanics or permission requirements for the purchase.

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

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

Three sentences, front-loaded with the purpose and branch model, then exclusions, then return values. Dense but nearly every clause carries information; the deprecated-name note is useful but slightly tacked on.

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, multi-branch tool with nested objects and no output schema, the description covers the return values per op and the token lifecycle well. The remaining gap is the undocumented secondary parameters (chain, family, params, receipt, transaction), which an agent would have to infer.

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 56%, and the description adds real meaning for 'op' (branch selection) and 'lifecycle_token' (one-time plc_ token from the purchase). However, several parameters — chain, family, params, receipt, transaction — get no explanation in either the description or the schema, leaving a meaningful gap.

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 ('buy a 24h Position Lifecycle bundle and run the guard, receipt and close steps') and enumerates the four branch values of 'op'. It also explicitly distinguishes itself from the sibling trade_guard, so an agent can tell the two apart 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 explicit when-not guidance: not for a single pre-trade guard (route to trade_guard op check_safety), not for unrelated positions, and not with a token after close. The alternative and the condition that selects it are both named.

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?

With no annotations, the description carries the full burden and does most of it: it discloses the prepaid 24h window, that the control token is one-time and must not be shared, the credit charge, and the exact return fields (lifecycleId, plc_ token, covered expiry). It does not say what happens if a lifecycle already exists for the subject, nor what an insufficient-credit or failure response looks like, which keeps it below 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?

Four compact sentences, front-loaded with the action and return value, then usage boundaries, then the return contract, then the deprecation notice last. No filler or restatement of the name; the security warning and sunset date each earn their place.

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

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

Only two simple parameters and no output schema, so the description must supply the return contract itself — which it does (lifecycleId, plc_ token, expiry, credits charged). It also flags the deprecation and removal date, so an agent knows to prefer the newer sibling, leaving nothing essential 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?

Schema description coverage is 100%, so both parameters are already documented; the description reinforces that symbol identifies the single "position subject" the bundle covers but says nothing about chain (e.g. whether omitting it defaults or errors). Baseline 3 is appropriate when the schema does the explanatory work.

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

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

"Buy a 24h Position Lifecycle bundle for one position subject and return the one-time control token" gives a specific verb (buy), a specific resource (lifecycle bundle), its duration and its output. It explicitly contrasts itself with check_trade_safety (single guard) and with position_lifecycle op "begin", so an agent can place it among 20 siblings 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?

States the positive condition (an agent needs guard, execution-receipt and close steps in one prepaid window), the negative condition (not for a single guard → use check_trade_safety), a security rule (never share the token), and a deprecation routing rule (prefer position_lifecycle with op "begin"). Both alternatives and the selection criteria are named explicitly.

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?

With no annotations supplied, the description carries the full burden and does well: it discloses credit cost (guard and receipt are free inside the bundle), the one-time nature of the token, the deprecation/removal date, and what each step returns. It stops short of describing failure behavior (expired/invalid token, out-of-order steps) or whether close invalidates the bundle beyond the token-reuse warning.

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 operation enumeration, then moves through cost, returns, constraints, and deprecation in a logical order with no filler. It is dense with several distinct concerns packed into one paragraph, which slightly reduces scannability but not substance.

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 steps in by naming what each op returns (guard verdict, signed receipt, combined summary), and it flags the deprecation and preferred replacement. Given 7 parameters with nested objects, the unexplained family/params/receipt shapes are 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 only 43%, and the description compensates for two parameters well: op values are explained and lifecycle_token's origin is stated. However family, params, receipt, and transaction (including the vague "old shape" hint) get no explanation in the description, leaving half the parameters undocumented in both places.

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 ("Run one step inside a purchased Position Lifecycle bundle") and enumerates the three operations with their meanings: guard, receipt, close. It also distinguishes itself from siblings by naming the deprecated status relative to position_lifecycle and by tying it to position_lifecycle_begin.

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 preconditions ("Use it only with a lifecycle token from position_lifecycle_begin"), explicit exclusions ("Do not use it for unrelated positions"), a hard constraint ("never reuse a token after close"), and an alternative ("prefer position_lifecycle with op 'guard'"). This is close to a complete routing decision.

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?

With no annotations, the description carries the full burden and does: it discloses the state enum (READY, CAUTION, REQUIRES_COMPLETION, BLOCK, UNAVAILABLE), that unprepared payloads are never labelled READY, that a venue-rest-order sets proves_onchain_execution: false, the signing requirement, and the limits of transactionHash/messageHash binding. It also reveals that a guard verdict is embedded per adapter, which is exactly the kind of non-obvious behavior an agent cannot infer.

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 contract is front-loaded in the first sentence and every substantive sentence adds a fact an agent needs (per-venue artifact, guard reference, envelope shape, deprecation). It is still a dense single block of long parenthetical clauses, and the defensive line about never returning "a uniformly described executable trade package" 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?

This is a complex four-variant, venue-polymorphic tool with no output schema, and the description still specifies the return envelope, payload kinds, the required validity_anchor, caller requirements and the guard reference. Nothing critical for calling or interpreting the result is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns one more by adding meaning the schema does not encode, notably that Synthetix acceptablePrice comes from Insight cross-oracle consensus rather than the mark price, and that the Solana Borsh payload must be completed with the Drift SDK. It does not walk through individual parameter names, which leaves it short of a 5.

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?

"Prepare an unsigned perpetual order for one reviewed venue, without signing or submitting it" names a specific verb (prepare), resource (perpetual order) and explicit boundary (unsigned, not submitted). It then enumerates the four venues and what each returns, which lets an agent distinguish this from siblings like issue_execution_receipt or check_trade_safety without reading 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?

"Use it when an agent has decided on venue, market, side and size" gives the precondition, and "Do not use it to create a nonce, sign, or submit an order" gives the exclusions. It also routes to the replacement explicitly (trade_guard with op "prepare_perp_order") and dates the removal, so an agent knows both the trigger and the deprecation path.

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?

With no annotations, the description carries the burden well: it discloses that output is unsigned, that signing/submission is out of scope, that a safety gate must be run, and that the tool is deprecated with a removal date. It omits auth/permission requirements and rate limits, keeping it 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?

Front-loaded with purpose, then usage constraints, then return shape, then deprecation. Dense but nearly every clause carries information; the venue enumeration is long but necessary for routing.

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 20-parameter, no-annotation, no-output-schema tool, the description covers the return envelope and safety-gate requirement but leaves most parameters and venue-specific requirements (e.g. which fields apply to solana_jupiter vs loopscale) unexplained.

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 only 20% across 20 parameters, and the description adds almost no per-parameter meaning beyond naming venues and mentioning a 'reviewed profile' and 'policy'. Fields like direction, min_lp_amount, principal_amount, collateral_value_usd, and the decision-price fields are left entirely to 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 ('Prepare unsigned, reviewed swap calldata') and enumerates the exact venues it covers, so an agent can distinguish it from quote or safety-check 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?

Explicitly gives the when ('user wants an executable transaction bound to a reviewed pool and policy'), the when-not ('do not use it to sign, submit or route arbitrary calldata'), and names the preferred alternative (trade_guard with op "prepare_swap").

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?

With no annotations, the description still discloses that this is a lookup returning registry rows or a single record with ids and reviewed metadata, which signals a read-only retrieval tool. It also flags deprecation and the sunset date, which is unusually useful context. It stops short of stating read-only guarantees explicitly or describing pagination behavior beyond the offset parameter, and the phrase "Deprecated alias" is slightly ambiguous about whether this tool or trade_guard is the deprecated one.

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 scope, then usage, then return shape, then the deprecation note — a sensible ordering with no filler. The deprecation sentence is slightly compressed to the point of ambiguity ("Deprecated alias: prefer trade_guard with op \"search_registry\""), costing a bit of clarity.

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, no-output-schema, no-annotation tool, the description covers the essential pieces: what is searched, when to use it, what comes back, and that it is being retired. What is missing is modest — no statement about result volume/paging, whether the deprecated tool behaves identically to trade_guard op search_registry, or any auth/permission expectation.

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 one of the 8 parameters (kind enum, query, limit, offset, category, chain_id, is_active, verify_onchain) is already documented in the schema. The description adds contextual meaning about the ids the search surfaces but no parameter-level syntax, defaults, or interactions. 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 (search) plus the exact resource families (symbols, feeds, protocols, stablecoins, protocol risk parameters, RWA instruments/context, settlement-evidence packs, setup recommendations) and explicitly separates itself from price/health siblings. An agent can tell it apart from get_oracle_price, get_oracle_health, and verify_evidence 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 a positive use case ("discover the exact ids a price, safety or execution tool expects"), an explicit exclusion ("Do not use it to read live prices or health"), and a named alternative plus deprecation date ("prefer trade_guard with op \"search_registry\"... Removed on 2027-01-06"). This is exactly the 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?

With no annotations, the description carries the full burden and mostly succeeds: it discloses per-op return payloads, the PASS/CAUTION/DANGER/BLOCK verdict shape, the fact that prepare_* returns an unsigned transaction/message/order rather than executing, and per-op credit costs. It does not cover auth requirements, failure behavior of the safety gate, or caching semantics beyond the existence of force_refresh.

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 use case, then exclusions, then returns, then deprecation, then metering — a sensible order with no filler. The opening sentence is dense and the metering sentence is long, but each sentence carries information an agent needs.

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 tool with 8 branches and 73 parameters, no annotations, and no output schema, the description is unusually rich on returns, cost, and aliases. The residual gap is the combinatorial parameter space: nothing tells an agent which subset of fields belongs to which op, which is the main way this definition could be misused.

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 only 53% across 73 parameters, so the description must compensate, and it does so only partially: it explains op semantics, the return per op, and per-op pricing, but never maps parameters to branches (e.g. which fields apply to prepare_perp_order vs check_safety). An agent must infer applicability from parameter names and enum values alone.

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

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

The description states a specific role — pre-execution trust decisions — and enumerates every branch it covers (oracle price, analytics, health, registry search, venue quote, safety gate, prepare_swap/prepare_perp_order). It also names the sibling tools it is not (trade_proof, oracle_watch_window, position_lifecycle), so an agent can route without opening any schema.

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

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

Explicit when-to-use ("every pre-execution trust decision") paired with three explicit when-not-to-use clauses, each naming the alternative and the condition that selects it. The dispatch rule ("Each call selects the branch with 'op'") closes the remaining loop on invocation.

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?

With no annotations, the description carries the full burden and does disclose return content per branch (session handle, signed receipt, verification verdict plus digest and matched evidence) and the credit cost per op. It does not say whether issue_receipt persists or writes anything durable, what permissions/keys are needed, or whether evidence sessions expire, which are the behavioral facts an agent most needs for a mutating ledger-style tool.

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

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

Four sentences, front-loaded with purpose before exclusions, returns and metering, and each sentence contributes new information. The metering sentence is dense but earns its place because cost varies per branch; the deprecated-alias sentence is borderline but useful for routing legacy calls.

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

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

The description covers purpose, alternatives, returns and pricing for a genuinely complex 25-parameter, three-branch tool with no annotations and no output schema. The remaining gap is significant: an agent cannot tell from the description which parameters are needed for begin_evidence versus issue_receipt versus verify_evidence, and there is nothing about failure modes, expiry, or signing prerequisites.

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?

Coverage is only 32% across 25 parameters, so the description needed to compensate and largely does not. Its only real parameter value-add is the metering split for kind (three offline kinds free, live reads billed C4); it never maps the many inputs (user, asset, action, providers, amount_usd, settlement, expected_order, decision_input, attestations) to the branch that requires them, and schema-supplied hints like decision being required for settle modes are only partially echoed.

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 concrete verb-and-resource set per branch (open a trade-evidence session, issue an execution receipt, verify an evidence artifact) and ties each to an explicit "op" value. It also states what the tool is NOT for, naming trade_guard and the venue guard tools, so an agent can separate it from 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 exclusions are given (do not use to decide trade safety → trade_guard; do not use to settle a swap guard → venue guard tools), and the phrase "after a trade" frames the timing. What is missing is guidance for choosing among the three ops themselves and which inputs each op requires, so the agent still has to infer branch prerequisites.

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?

No annotations are supplied, so the description carries the full burden; it does disclose the return payload (valid/invalid, closed-loop or settlement status, binding assertions, machine-readable reasons) and the deprecation timeline. It does not state that the operation is side-effect-free/read-only, nor any auth or rate-limit expectations, which matters for a tool an agent may call repeatedly against third-party claims.

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

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

Four dense sentences with the purpose and scope front-loaded, followed by usage boundaries, return shape, and deprecation. Little waste, though the deprecation/migration warning is buried at the end rather than surfaced where an agent would see it 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 usefully summarizes the return values, and it handles migration and non-goals well. However, for a 9-parameter tool with deeply nested payload objects and no schema descriptions, the description leaves an agent unable to assemble correct per-kind inputs, which is a material completeness 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 0% across 9 parameters including four nested free-form objects, so the description must compensate. It only clarifies the `kind` enum by paraphrasing the four artifact types; user, order_id, submitted_at, settlement, expected_order, execution_receipt, pre_trade_attestation and destination_pre_trade_attestation are left entirely unexplained, including which are required per kind.

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 ("Verify signed evidence") and then enumerates the four artifact types it covers (pre-trade/execution pair, Base agent-swap settlement, Solana swap settlement, Hyperliquid order/fill), which map directly to the `kind` enum. This clearly separates it from siblings like check_trade_safety, trade_guard, and get_oracle_health.

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 ("when a third party needs to check binding and signatures before trusting a claim") and explicit exclusions ("Do not use it to re-assess oracle risk or to authorize trading"), naming the sibling responsibilities it should not absorb. It also routes to the replacement tool trade_proof with the exact op value.

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