Tollbridge

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

Annotations only declare it as a read-only, idempotent, open-world call; the description goes well beyond that by stating that no payment field joins the ranking, that paying cannot improve standing, and that a wallet with a record but no opt-in is omitted entirely rather than shown. These are meaningful behavioral guarantees an agent could not infer from the annotations.

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

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

The ranking axes and opt-in rule are front-loaded well, but the paid-vs-free point is made three times ("FREE", "paying more cannot move you up", "No payment required"), which 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?

An output schema exists, so return structure need not be described, and the eligibility/ranking model is well covered. The main residual gap is any hint about limit behaviour or default result size for a board capped at 200.

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%, so the description must carry parameter meaning, yet it only echoes the enum values already present for sort (adding that XP is the default, which the schema lacks) and track. The limit parameter, its 1–200 range, and any pagination semantics are never mentioned.

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 (the public arena leaderboard over opted-in players) with its scope and ranking axes (XP default, accuracy, streak) and tracks (human/agent). This is clearly distinguishable from sibling arena tools like profile, levels, season, and quests, which cover different concerns.

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 establishes clear eligibility context — free, public, and only opted-in wallets appear — so an agent knows the preconditions before calling. It does not, however, name alternatives or a when-not condition relative to the sibling arena tools, so exclusions are absent.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the lower bar applies. The description adds useful context beyond them: that the tool is free, requires no payment, and returns static data — reinforcing safe, repeatable, side-effect-free reads. It stops short of describing return shape or pagination, which the output schema presumably covers.

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 label ('FREE — THE LEVEL CATALOG') and enumerates its contents efficiently. The free/static/no-payment idea is stated three times across the sentence, which is mild redundancy, but the overall length is justified for a catalog that must advertise its contents.

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

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

An output schema exists, so return-value detail is not required. The description enumerates exactly what the catalog contains (level bands, cost ranges, XP values, rank ladder, thresholds, discounts) and confirms it is static and free, giving an agent everything needed to decide to call it and what to expect.

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. The description correctly implies a parameterless lookup with no filtering options, and there is nothing in the schema for it to clarify or contradict.

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 (the Intelligence Level bands IL1..IL5+ and the earned rank ladder) with concrete contents: credit cost ranges, XP per ask and per correct call, XP thresholds, and credit-cost discounts. It is easily distinguished from siblings like leaderboard, profile, pricing, or profile, since it is explicitly a static reference catalog rather than player state or a query endpoint.

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

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

It gives clear usage context ('Read this before you ask') plus the reason to consult it (how the price of a question and earned XP are derived), which is strong guidance for a reference tool. It does not name alternatives or explicit when-not conditions, but for a static self-contained catalog there isn't much to exclude.

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, so the safety profile is covered. The description adds real behavioral context beyond that: the ranking is deterministic arithmetic, no payment is required despite the 'payer' parameter, the agent-track declaration is echoed back, and the total available XP is reported.

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 key value proposition is front-loaded in an ALL-CAPS lead phrase and the supporting details follow in a compact flow. There is mild marketing padding ('never an opinion, never paid') that could be trimmed, but nothing is buried.

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

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

An output schema exists, so return-value detail is not required, and annotations cover the safety profile. What remains is adequately covered: the inputs, the free/no-payment guarantee, and what the response contains are all described for a one-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 coverage is 0% for the single 'payer' parameter, so the description must compensate. It does clarify that the caller supplies their own payer/wallet address and that this is not an actual payment, resolving the misleading parameter name, though it does not specify the address format.

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: rank the open quests for your wallet by XP reward and remaining effort, and return a recommended next action. It is clearly distinguishable from a plain quest list or leaderboard, but it never names a sibling tool (e.g. tollbridge_arena_quests) to sharpen the boundary.

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

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

Usage is implied rather than stated: use this when you want to know what earns the most XP next. The 'never an opinion, never paid' contrast hints at when alternatives (paid/opinion-based tools) might be relevant, but no alternative is named and no when-not condition is given.

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, so the safety profile is covered. The description adds genuinely useful non-schema behavior: the response is free of charge, ranks are earned from XP and never purchasable, and a wallet with no history returns honest zeros rather than a fabricated rank — a real edge-case disclosure.

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

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

Front-loading 'FREE — YOUR ARENA STANDING' is good, but the long mid-sentence enumeration of every returned field (rank tiers, XP, discount, accuracy, streaks, markets, badges) largely duplicates the output schema, which the tool already has. Per the guidance that return values need not be re-explained when an output schema exists, this list is more padding than 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?

With an output schema present, the description is not obligated to describe the return shape, and it correctly spends its words on cost, honest-zero behavior, and what the payer input means. For a single-param read tool this is nearly complete, missing only an explicit sibling comparison.

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 0% and the single parameter 'payer' has no description, so the description carries the load. It compensates well by stating the value is your wallet address and that the lookup is 'keyed by your wallet address', making the required input unambiguous. It could still clarify address format, but the semantic intent is clear.

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 ('YOUR ARENA STANDING') and the key that scopes it ('keyed by your wallet address'), and enumerates exactly what the profile contains. It is clear what the tool retrieves, but it never names or contrasts itself with the sibling leaderboard/levels tools, so an agent must infer the boundary between 'my standing' and 'everyone's standings'.

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 only implied: the repeated 'FREE' and 'No payment required' framing signals this is a zero-cost lookup to call when the agent wants the caller's own standing. There is no explicit statement of when to prefer this over tollbridge_arena_leaderboard or tollbridge_arena_levels, and no prerequisites are stated beyond supplying the payer.

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, but the description adds real value: progress is derived from an append-only XP journal with 'no separate counter,' and it preempts the natural confusion that a required 'payer' implies payment by stating 'No payment required.' That resolves a non-obvious behavioral trap.

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 key framing ('FREE — THE QUEST BOARD') and the rest is informational. Slightly wasteful in repeating the no-cost point twice ('FREE' and 'No payment required'), but overall tight for the amount of detail conveyed.

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

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

With an output schema present, the description need not explain return shape, and annotations cover the safety profile. It gives the agent the framing (free, journal-derived progress, required payer) needed to call it correctly, missing only explicit sibling routing.

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 0% and the single 'payer' parameter is undocumented in the schema, so the description carries the burden. It clarifies that 'payer' is an address to name and is not a payment trigger, which is more than the schema provides, though it does not state the address format.

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 ('the daily and weekly quests with your live progress') and what each entry contains, so the agent knows exactly what comes back. It reads clearly as the quest-board retrieval tool, though it never explicitly contrasts itself with near-siblings like tollbridge_arena_next_action or tollbridge_arena_leaderboard.

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 only implied: 'Complete one to bank its XP toward your next rank' hints at why an agent would fetch the board, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool. Adequate but leaves the agent to infer routing.

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

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

Annotations already declare readOnly/idempotent/openWorld, yet the description adds substantial behavior: the weekly reset cadence, that badges never expire, that figures are measured from an append-only XP journal and graded calls ('never invented'), and that public rank requires opt-in. This is well beyond what 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?

Front-loaded with the key benefit and scoping ('FREE — YOUR SEASON STANDING'), and most sentences carry information. The all-caps emphasis and long single paragraph add some noise, but little is truly 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?

An output schema exists, so return values needn't be documented, yet the description still covers cadence, measurement source, opt-in gating, and badge permanence. Combined with the 1-param schema, the only real omission is payer-address format.

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% for the single required 'payer' parameter, so the schema carries no meaning. The description compensates partially by clarifying it is a payer address and that 'no payment is required', but it gives no format or example, leaving a real 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?

States a specific verb+resource ('names the live season key, when it started and when it ends, and YOUR season facts') and enumerates the exact outputs: season XP, calls locked, correct resolutions, accuracy, trailing streak. It implicitly separates itself from tollbridge_arena_leaderboard by noting the public rank only appears for opted-in wallets.

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

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

The description explains the opt-in prerequisite and points to POST /v1/arena/opt-in, which is useful context, but it never explicitly says when to call this instead of tollbridge_arena_leaderboard or tollbridge_arena_profile. Usage is implied ('YOUR season standing') rather than routed.

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/openWorld annotations, it discloses cost and side-effect behavior ('no payment required, no clocks are started or credits spent'), partial-failure semantics (an unknown symbol is skipped with a typed warning rather than 404-ing the whole blotter), the 20-asset cap, and the empty-result contract ('an empty pending is []: data, not a fabricated "none"'). This is unusually rich behavioral disclosure that annotations alone would not 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 description is front-loaded ('FREE — MANY ASSETS, ONE OBJECT') and every sentence carries information: output-field semantics, parameter behavior, failure mode, and the agent loop. It is dense and jargon-laden, which costs some readability, but there is little 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?

Although an output schema exists, the description still frames what the three row sets mean, covers the parameter default/cap, documents degraded-mode behavior, and closes with an end-to-end agent loop. Nothing an agent needs to call it correctly or interpret partial results is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds meaning beyond the schema by stating the 20-asset cap (the schema only bounds maxLength at 400 characters) and reaffirming the BTC,ETH,SOL default and skip-with-warning behavior. It does not add format or ordering guidance beyond what 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?

The description states a specific resource and scope: a cross-asset cut of the question sheet returning open clocks ('pending'), last dead chips ('latest_terminal') and blocked questions ('dark') for the named assets. It differentiates from siblings by explicitly linking to tollbridge_sheet and GET /v1/clocks/open as the single-source equivalents. However, the heavy proprietary jargon ('dead chip', 'question sheet', 'blocked question') makes the exact purpose harder to parse than a plain verb+resource statement.

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 usage context and an operational workflow: read the blotter, sleep until min(pending.horizon_end), read the resolution, then ask only rows where ask.allowed == true. It also signals this is the free, multi-asset read. It stops short of stating when to prefer it over tollbridge_sheet or tollbridge_open_clocks, which it only cites as consistency references rather than alternatives.

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

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

Annotations already declare readOnly, idempotent and openWorld, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are publication-gated, sub-floor buckets return counts with published: false, and 'n too small' is data rather than an error — critical for correct result interpretation.

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?

Single dense sentence with the key framing ('FREE', 'per question') front-loaded and no filler. It is somewhat clause-heavy, but each clause carries new information about output shape or gating behavior.

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

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

An output schema exists and the description still usefully characterizes the returned buckets and the published-flag semantics. However, the undocumented 'subject' parameter and the absence of any use-case routing leave clear gaps for a tool with two inputs.

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% for both parameters. The description's 'per question' only obliquely implies question_id (whose enum values are self-describing), and the 'subject' parameter is never mentioned or defined anywhere, leaving it fully undocumented.

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 deliverable — a reliability calibration keyed per question, returning decile buckets with a predicted-band midpoint and realized empirical frequency. An agent can tell it is a read-only reporting tool rather than a market-state or decision tool. It does not explicitly differentiate itself from the many tollbridge_* siblings, so it falls short of a 5.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative among the 33 siblings. 'FREE' and 'No payment required' hint that it is cheap to call, but that is a cost note, not usage 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false) by disclosing cost model (free; credits spent on the opening ask), the invariant that the house number is frozen, two concrete error codes (409 CLOCK_CLOSED, 409 CALL_LOCKED), and that the same evaluator grades both sides. This is exactly the mutation/reversibility/idempotency context an agent needs and annotations alone don't supply.

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 fact (FREE) and densely packed with useful clauses in a logical order. The all-caps emphasis ('BEAT THE HOUSE', 'FREE', 'OWN') is slightly stylized but each sentence still carries distinct information rather than padding.

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

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

With an output schema present, return values needn't be explained, and the description covers prerequisites, cost, immutability, idempotency, and error codes well. The one real hole is the unexplained call_probability parameter, which an agent cannot resolve from schema or description.

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 0% and there are no enums, so the description must carry the load. It does well for the two required params, defining `call` as "obtains"/"not" for probability questions or the question's own label for choice questions, and implying decision_id is an open-clock id. However, the optional call_probability (0-1) parameter is never mentioned anywhere, leaving one of three params entirely undocumented.

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 ('Lock your OWN call on an OPEN clock') with the exact payload shape ({decision_id, call}). It clearly distinguishes itself from tollbridge_open_clocks (source of ids) and tollbridge_calls (the record), so an agent can tell the three apart 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 the precondition ('before its horizon', clock must be open), the sequencing rule ('Read tollbridge_open_clocks for open clock ids first'), and the follow-up destination ('your record is tollbridge_calls'). The when-not conditions are also explicit: immutable after horizon_end and one call per payer per clock.

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 behavior, so the bar is lower. The description adds genuinely useful traits beyond them: null handling ('n=0 reports nulls, never fabricated zeros'), scoring direction ('lower is better'), the 0/1 grading of a bare certainty call, and that no payment is required. It does not spell out auth/permission requirements for the payer, 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?

Front-loads the headline ('FREE — YOUR SCOREBOARD AGAINST THE HOUSE') and packs metrics, semantics, and scope tightly into one paragraph. Slight redundancy between 'FREE' and 'No payment required' is the only waste, and every other clause adds call-relevant information.

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

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

With an output schema present, the description needn't re-explain return values, yet it usefully disambiguates them (null handling, lower-is-better Brier). Combined with annotations and the single required parameter, it is nearly complete; only the absence of sibling routing guidance leaves a small gap.

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

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

Schema description coverage is 0%, so the description must carry the parameter's meaning, and it does: payer is your address and it scopes the read to your own calls only. The format (0x pattern) is left to the schema, but the semantic role of the parameter is clarified beyond the bare name.

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 deliverable: a personal scoreboard of your own calls graded against the house on identical events, enumerating the returned metrics (n, graded, open, accuracy, both Brier scores). It also distinguishes itself from the leaderboard sibling by declaring 'no public leaderboard exists', so an agent can route correctly 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 the key precondition ('name your payer address and this reads only your own calls') and the scope boundary (personal, not public), which implies when it applies. However, it never contrasts with near siblings like tollbridge_arena_profile or tollbridge_calibration, so the when-to-use-this-vs-that decision 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?

Well beyond the annotations, the description discloses the payment profile (x402 exact USDC on Base / Scout credits, `payer` argument, x-tollbridge-payer header, PAYMENT-SIGNATURE), that unpaid calls return a payment_required challenge and never fabricated data, that refusals refund the debit, and that unknown/delisted symbols yield a typed 404. It adds genuine behavior the readOnlyHint/openWorldHint/idempotentHint trio does not cover; the one gap is that it never reconciles the paid, debit/refund nature with the declared readOnlyHint.

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 opens with payment mechanics rather than purpose, then dumps a huge LIVE-set enumeration in which the same IDs repeat verbatim (X05 five times, X06 five times, X09 six times, S01 twice), inflating length without adding information. The genuinely useful parts (agent loop, refusal/refund semantics, payment rails) are scattered across the wall of text instead of front-loaded.

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

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

An output schema exists, so return-value detail is not required, and the description covers payment, refunds, refusals, 404s, and the resolution-polling loop. However, for a tool with 5 parameters and a large question catalog, it leaves `question_version` undefined and the duplicated LIVE list makes it impossible to tell how many distinct askable questions exist, which an agent needs before invoking.

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%, so the description has to carry the load and largely does: it explains that `asset` may be any symbol tollbridge_universe lists and that unknown symbols produce a typed 404, enumerates the askable `question_id` values and what each one queries (asset vs wallet, funding, OI, tape, etc.), and explains the `payer` alternatives and format. It never explains `question_version`, and the duplicated question list muddies the mapping.

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 sentence 'Deep decision: ask a catalog signal through the decision engine for an asset on base — probability, confidence, policy verdict, horizons and ledger-grade provenance' gives a specific verb+resource and even names the outputs. It is clear, but the purpose is not front-loaded (the description opens with payment rail mechanics) and it never contrasts itself with near-siblings such as tollbridge_get_decision, tollbridge_get_resolution, or tollbridge_call, so sibling differentiation is left to inference.

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

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

It gives a concrete operating loop ('get latest → get resolution → if terminal and the question is available, ask the NEXT dated sentence') and states that blocked questions S02/S03/S04 return a typed out_of_scope refusal rather than a gradeless probability. That is actionable context, but it never says when to pick this tool over the other decision/query siblings, so there are no explicit alternatives.

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

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

Discloses a lot beyond annotations: the billing.export.asset_period debit, replay idempotency, debit reversal on failed generation, refusal refunds, payment_required challenge for unpaid calls, and redaction of another payer's private subjects to null. This is consistent with idempotentHint=true and readOnlyHint=false (the call debits billing), no contradiction.

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 essential purpose well, but the payment sentence 'After paying, poll /v1/resolutions/:id until horizon_end' is repeated verbatim and the payment/refund rules are spread across several clauses, adding redundancy that dilutes the core 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?

An output schema exists, so return-format explanation is unnecessary; the description instead covers the payment path, replay/refund semantics, and refusal behavior. It is nearly complete for a paid export, with only the from/to window mechanics slightly under-specified.

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 0% schema description coverage the description must carry the parameter load, and it does for payer (Base 0x… address, or x-tollbridge-payer header, or PAYMENT-SIGNATURE), scope (asset vs question), subject, and format (CSV/JSONL). The from/to date-time parameters are only implied by 'one UTC calendar month' and 'narrow the period' rather than named, leaving a small 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?

States a specific verb and resource — export the decision history for one subject (asset symbol or question id) over one UTC calendar month — and enumerates the record fields (claim, distribution/probability, confidence, hashes, decided_at, horizon, outcome). An agent can distinguish this bulk-export tool from per-item readers like tollbridge_get_decision or tollbridge_blotter.

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 clear conditions: it's a paid add-on, requires a payer, one subject+month is a typed replay (never a second charge), and an oversized window is refused uncharged so the agent should narrow the period. It does not, however, explicitly route against sibling tools for the same subject (e.g. get_decision / get_resolution), leaving some alternative-selection to inference.

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

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds real value: free, no wallet, no payment, no pending rows, and the null semantics for no-claim rows. It discloses the limit default (50) and cap (200). Return-shape detail is partly redundant with the existing output schema, keeping it from a 5.

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

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

Front-loaded with 'FREE — THE TAPE,' which is good, but the body is dense and repetitive ('no wallet, no model guts' and 'No payment required' restate the same point). Multiple clauses on row semantics could be trimmed given an output schema already exists.

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 an output schema exists, the description needn't define return values, yet it goes further by explaining CHOICE vs PROBABILITY rows and no-claim labeling. Combined with the routing to pending-row siblings and the growth-loop workflow, an agent has enough 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 0% and the single param (limit) is undocumented in schema, so the description must compensate — and it does, stating the default of 50 and the cap of 200. That fully covers the only parameter, though it doesn't mention the exclusiveMinimum constraint.

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 (the newest terminal chips / feed, newest-first) and clearly frames it as a read-only tape of resolved decisions. It distinguishes itself from pending-row siblings by pointing to tollbridge_blotter and tollbridge_open_clocks. The jargon 'chips'/'terminal' is opaque at first read, slightly blunting clarity.

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 routes the agent: use this feed for landed results, and go to tollbridge_blotter / tollbridge_open_clocks for open clocks. It also lays out the growth loop (feed → tollbridge_decision → tollbridge_get_resolution → land here). No explicit 'when not to use' beyond the pending-row exclusion, so a 4 rather than 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?

Goes well beyond the annotations: it discloses the paid model, the `payment_required` challenge behavior, that unpaid calls 'never fabricate data,' that a refusal refunds the debit, the required polling loop until horizon_end, and explicit modeling assumptions (economics_modeled: none; S06/S07 LIVE). This is rich operational context an agent needs before invoking the 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?

The single dense paragraph is not front-loaded — it opens with payment instructions before stating what the tool does — and the instruction 'after paying, poll /v1/resolutions/:id until horizon_end' is stated twice verbatim. Multiple run-on semicolon-joined clauses make it hard to parse, and the repetition is wasted space.

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

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

With an output schema present, the description need not explain return values, and it correctly focuses on payment flow, polling, refund semantics, and engine assumptions. It is nearly complete for this paid scan; the main omission is any explicit pointer to alternative sibling tools for related decisions.

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 single `payer` parameter has 0% schema description coverage, so the description must carry it, and it does: it defines payer as a Base address (0x…) and offers alternative carriage via HTTP header or PAYMENT-SIGNATURE. It compensates for the coverage gap, though it does not restate the exact regex/format constraint present 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?

The description names a specific resource and action: a 'Funding-anomaly scan across BTC/ETH/SOL' returning per-asset funding (bps), basis (bps) and the S06 engine decision, which is concrete and identifiable. It differentiates itself from generic siblings by naming the S06/S07 engines and the funding/basis scope. Purpose is present but is buried behind an opening payment-mechanics clause rather than front-loaded.

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

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

The description gives clear payment/usage mechanics (pass `payer`, send `x-tollbridge-payer` header, or x402 PAYMENT-SIGNATURE, then poll /v1/resolutions/:id) and states the tool is 'a policy verdict, not a trade.' However it never says when to choose this scan over siblings such as tollbridge_decision, tollbridge_market_state, or tollbridge_get_intelligence; context is implied rather than routed.

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, so the safety profile is covered, but the description adds real behavioral context: append-only ledger, an immutable snapshot that is never recomputed, and a typed DECISION_NOT_FOUND refusal for unknown ids. It also flags that no payment is required, which matters on a paid platform. It does not discuss rate limits or auth, hence 4 rather than 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-loads 'FREE read' and the lookup key, then enumerates the returned fields, error behavior and cost in compact clauses. Minor redundancy between the leading 'FREE' and the trailing 'No payment required', which is the only thing keeping it from 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 a single-param read with an output schema, the description supplies everything the schema and annotations cannot: the immutability guarantee, the shape of the record (probability, confidence, policy verdict, hashes, payment linkage), the typed error for missing ids, and the zero-cost property.

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

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

There is only one parameter, and the schema itself fully constrains it (string, uuid format, explicit pattern). The description restates 'by decision_id (UUID)' without adding semantics the schema lacks, so this is baseline adequacy.

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

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

The description gives a specific verb (read) plus resource (a past decision from the append-only ledger) and the lookup key (decision_id UUID), and it implicitly separates itself from tollbridge_decision by stressing 'past' and 'never a recomputation'. It stops short of naming the sibling tools (e.g. tollbridge_decision, tollbridge_get_resolution) explicitly, so differentiation requires a small inference.

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

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

Usage is implied: use this when you already hold a decision_id and want the recorded decision rather than a fresh computation. There is no explicit when-not guidance and no named alternative tool, so an agent must infer that recomputation lives elsewhere.

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 and openWorld, so the safety profile is covered. The description adds real behavioral context beyond them: the index-floor suppression behavior, the rule that a null composite is NOT a zero, and the guarantee that below floors the payload carries counts and a plain sentence rather than a fabricated score.

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 two useful facts (FREE, THE MEASURED RECORD), but the body is a single sprawling sentence that enumerates return fields already covered by the output schema. It is dense and informative yet padded with redundant payload listing, so structure is serviceable rather than tight.

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 annotations, a zero-arg schema and an existing output schema, the definition is more than complete for correct invocation; the description needn't restate return values but does. Nothing needed to call it correctly is missing, only some redundancy remains.

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 (empty schema, additionalProperties false), so there is no per-parameter meaning to convey; baseline for a no-arg tool is 4. The description correctly signals the tool is a pure read with no inputs.

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 (the Decision-Intelligence Index as published at GET /v1/intelligence) and enumerates the exact payload contents — composite, Brier decomposition, evidence counts, price ladder. It is highly specific about what the tool returns, though it never explicitly names a sibling or contrast tool (e.g. tollbridge_calibration, tollbridge_pricing) to help an agent choose among the many tollbridge_* reads.

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?

"Agents buy on this read: 'is the judgment worth the price?'" implies the decision context in which to reach for it, and "Free read — no payment required" clarifies cost. But there is no explicit when-to-use vs. when-not, and no named alternatives, leaving routing among the ~30 siblings 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 cover read-only, idempotent, and open-world traits, yet the description adds real behavioral context: it is free (no payment), returns a dated pending shape while the horizon is open, never infers an outcome, and raises a typed DECISION_NOT_FOUND refusal for unknown ids. It does not mention rate limits or pagination, but the added disclosure is substantial.

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 point is front-loaded ('FREE resolution outcome ... by decision_id'), but the rest is one long run-on sentence dense with pipes, parentheticals, and jargon that is harder to parse than the payload warrants.

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

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

With an output schema present, return values needn't be explained, yet the description helpfully characterizes the outcome shapes and pending state, and covers payment and error behavior. For a one-parameter read tool it is close to complete; only routing and pagination are absent.

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

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

Schema description coverage is 0%, so the description must carry decision_id's meaning: it identifies a settled decision, is a UUID (matching the schema format), and unknown ids produce a typed DECISION_NOT_FOUND refusal. That compensates well for a single undocumented parameter.

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: fetch the resolution outcome for a decision_id, and spells out the possible outcome values (realized/obtains/not/unresolvable/pending). It is conceptually distinguishable from tollbridge_get_decision, but it never names a sibling tool, so the differentiation is left implicit.

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

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

Usage is implied — call it to get the settled outcome of a decision — and it clarifies that outcomes are never inferred and that ids must be known. However, it gives no explicit when-to-use/when-not guidance and never names an alternative such as tollbridge_get_decision, leaving routing 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?

Adds substantial behavior beyond the annotations: it debits the billing.addon.hook add-on, buys a 30-day window, never re-serves the signing secret, checks the URL at registration (refusing loopback/private/metadata hosts), returns a payment_required challenge when unpaid, and refunds on refusal. This aligns with (and enriches) idempotentHint=true and openWorldHint=true rather than contradicting them.

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 purpose is front-loaded, but the text repeats verbatim phrases — 'x402 exact USDC Base' and 'After paying, poll /v1/resolutions/:id until horizon_end' both appear twice — and the payment rail details are dense. It is informative but wastes space on duplication.

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

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

With an output schema present (so return values need no explanation) and only two params, the description covers payment, registration semantics, secret handling, and URL validation. It is close to complete for a paid write tool, with only minor gaps in post-registration expectations.

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%, so the description must carry the load, and it largely does: `payer` is framed as a Base address 0x… with three accepted delivery channels (tool argument, x-tollbridge-payer header, PAYMENT-SIGNATURE), and `url` as a public http(s) URL validated at registration. That is meaningful semantics absent from 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?

Names a specific verb+resource: 'register an outcome hook endpoint: a public http(s) URL that Tollbridge POSTs to when one of the payer's decisions settles'. This is unambiguous and clearly distinct from every sibling (leaderboards, blotter, risk, etc.), none of which manage webhooks.

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 clear operational context: register after paying, then poll /v1/resolutions/:id until horizon_end, and notes that re-registering the same URL inside its window replays without a second charge. It lacks explicit 'do not use this when…' guidance, but no sibling competes for this function, so the routing need is low.

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 annotations covering only readOnly/idempotent/openWorld, the description adds substantial non-obvious behavior: request_hash is recomputed in-handler and never rewrites the journal, a mismatch returns request_ok: false, a pre-trace row honestly reports 'unknown' rather than true, resolutions are terminal-or-honest-pending and never fabricated, and an unknown id yields a typed DECISION_NOT_FOUND refusal. This is exactly the kind of trust/verification semantics 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 free/evidentiary framing is front-loaded, but the body is a dense run-on with heavy emphasis that enumerates bundle contents already described by the output schema, so several clauses are partially redundant. The verify-block semantics earn their place, but the phrasing is more verbose than needed for a one-parameter 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?

For a single fully-documented parameter with an output schema present, the description covers use case, refusal behavior, honesty guarantees and the no-payment/no-live-call constraints, leaving little gap. Its enumeration of return contents overlaps the output schema, but 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 coverage is 100% and there is a single required parameter, so the baseline is 3. The description restates the UUID-or-8-char-prefix contract already present in the schema description, adding only the behavioral consequence for a non-resolving id (DECISION_NOT_FOUND), not new format or syntax guidance.

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: it returns the full evidentiary bundle for a single decision (record, resolution, payment leg, tape sources, verify block). It also distinguishes itself behaviorally from live-call siblings ('No live model call, no second venue'), though it never names the siblings directly. 'Lineage bundle' is jargon, but the elaboration makes the purpose concrete.

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

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

Usage is implied via the use case ('everything a hostile auditor needs to reconstruct the forecast, the payment and the grade') and via contrast ('No live model call, no second venue', 'No payment required'), which hints at when to prefer this over live-call or paid tools. However, with 30+ siblings including tollbridge_decision, tollbridge_get_decision and tollbridge_get_resolution, no alternative is explicitly named or excluded, so routing 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?

Goes well beyond the annotations: it discloses that calls are paid (x402 USDC/Scout credits), that refusals refund the debit, that refusal codes follow a published taxonomy, that unpaid calls return a payment_required challenge, and that the tool polls /v1/resolutions/:id until horizon_end. The only mild tension is that readOnlyHint=true while the description says the call debits/refunds credits, but since the payment mechanics are fully spelled out the agent is not misled.

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 oversized and back-loaded: the first sentence is payment plumbing rather than the tool's purpose, and 'after paying, poll /v1/resolutions/:id until horizon_end' is stated twice. The refusal codes are likewise given twice ('out_of_scope / insufficient_sample' then the full taxonomy), so meaningful redundancy undercuts the density of 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?

With an output schema present and annotations covering safety/open-world hints, the description supplies the remaining critical context: payment requirement, refund policy, refusal semantics, current unavailability, and polling behavior. It is essentially complete for invocation decisions, missing only a crisp statement of the quantity being estimated and the horizon semantics.

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 50% (asset is documented, payer is not), but the description compensates for payer by giving three concrete settlement paths (tool argument `payer` as a Base 0x… address, `x-tollbridge-payer` header, or an x402 PAYMENT-SIGNATURE). It also clarifies the asset domain ('any symbol the venue universe lists — not only BTC/ETH/SOL'), adding meaning beyond the schema pattern.

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 never plainly states the analytical purpose (e.g. 'assesses market-wide liquidation risk for an asset over a horizon'); it opens with the payment rail and availability status. The scope is inferable from 'the market-wide liquidation tape' and the implicit probability output ('never fabricate a probability'), and it is loosely differentiated from siblings like tollbridge_token_risk/transaction_risk, but the core verb+resource is left to the name/title.

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 tool is NOT available yet and the exact preconditions that turn it on (operator mounts a Hyperliquid node trade stream at NODE_TRADES_DIR, sets LIQUIDATION_SOURCE=node_trades, and 24 hourly observations). It also names the alternative data sources (per-wallet fills, node trade files) and points at tollbridge_universe for valid assets. It stops short of naming a sibling tool to call instead, which keeps it off a 5.

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

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

Annotations already cover read-only/idempotent safety, and the description adds real context beyond them: the feed is free with no payment required, results are ordered newest-first, and rejected candidates include the failing gate reason. It does not contradict any annotation. Missing only things like pagination or volume 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 load-bearing facts are front-loaded, but the description is padded with promotional and philosophical asides ('the forge's failures are part of the record, never hidden', 'never silently self-tuned') that add length without helping an agent decide or call. Roughly a third of the text could be cut with no loss of operational meaning.

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

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

An output schema exists, so return shape need not be explained, and the description still covers content, filtering, ordering, and access terms. What's missing is guidance on result volume or whether the unfiltered feed is paginated, which matters for a tool that is explicitly read-only and open-world.

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 0%, but there is a single parameter whose enum values are spelled out in the description ('status (candidate | active | superseded | rejected)') and whose filtering behavior (all results when omitted) is explained. That is adequate semantics for one enum param, though the values themselves are not defined individually.

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 ('the release feed: every intelligence release with its measured deltas AND its rejections') and enumerates the payload fields (version, parent, status, dataset window/hash, walk-forward evaluation, four promotion gates). This is clearly distinguishable from siblings like tollbridge_get_intelligence or tollbridge_lineage, which are not described as full proof-feed enumerations.

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 one concrete usage rule — 'Filter with `status`; without a filter the whole feed serves, newest first' — which is genuinely actionable. However, it never states when to choose this over related siblings (e.g. tollbridge_get_intelligence, tollbridge_decision), so routing guidance is implied at best.

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 readOnly/openWorld/idempotent annotations: it discloses cost (free, no payment required), caching behavior, data provenance (named public source, never curated), and the semantics of the 'quality' field real vs degraded on a failed refresh. It also explains the tri-state 'askable' flag and that null means the venue could not be read rather than a false negative.

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 dataset scope, and the routing distinction ('NOT the ask authority') appears early. It is dense but a few parenthetical clauses (e.g. 'never a lie in either direction') cost more words than they add.

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

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

An output schema exists, so return structure needn't be restated, yet the description still contextualizes the derived 'askable' and 'quality' fields usefully. Cost, caching, freshness and dataset origin are all covered; only the limit range/bounds remain 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 0%, so the description carries the load: it reveals the default of 50 ('top 50 by default'), which the schema does not. However, it never mentions the maximum of 250 or the valid range for 'limit', leaving part of the single parameter's semantics undocumented.

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 (market-cap list of the largest coins, rank-ordered with market cap, price and 24h change) and explicitly scopes it as the DISCOVERY list rather than the ask authority. An agent can distinguish it from siblings like tollbridge_call 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?

Clearly frames when to use it ('the DISCOVERY list a user picks a subject from') and when not ('it is NOT the ask authority'), which is the key routing decision. It does not name the alternative tool explicitly (e.g. tollbridge_call), so the exclusion is implied by role rather than by name.

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

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

Annotations already cover read-only, idempotent and open-world semantics, and the description adds genuinely new behavioral context: it is free under an open-data carve-out, no payment is required, it makes no probability claim, and the payload carries provenance and freshness. It still says nothing about rate limits or staleness thresholds, keeping it below 5.

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

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

Two tight sentences, with the payload contents front-loaded before the pricing caveat. The emphasis words ('FREE', 'no probability claim is made') cost a little density but earn their place as routing signals.

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

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

With an output schema present the description need not explain return values, and one required parameter plus rich annotations leave little burden. It is complete enough to call correctly, with only the asset-scope mismatch as a residual risk.

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

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

Schema coverage is 100% and the single `asset` parameter is fully documented in the schema, so the baseline is 3. The description's 'for BTC/ETH/SOL' framing actually narrows the asset scope relative to the schema's 'any symbol the venue universe lists', adding a mildly misleading gloss rather than useful 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?

The description names a specific verb+resource (market snapshot) and enumerates the returned fields (fresh quote, derived mid and spread in bps, provenance, freshness), so an agent knows exactly what comes back. It does not, however, distinguish itself from near-neighbors such as tollbridge_marketcap or tollbridge_pricing, so it stops short of a 5.

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 only implied: an agent can infer 'use this to get a spot quote' and the free/no-payment note helps route against paid siblings, but no alternative tool is named and no when-not-to-use condition is given.

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 readOnlyHint/idempotentHint/openWorldHint, it discloses that no credits are spent ("This tool never asks"), that an empty list is valid DATA rather than an error, and that a degraded upstream returns a typed refusal instead of an invented row. That is substantive behavioral context annotations cannot express; it omits rate limits and any auth/prerequisite notes.

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 routing are front-loaded and tight, but the parenthetical enumeration of 51 question IDs is bloated and partially redundant (X05, X06, X07, X08, X09 each repeated multiple times), which reads as an artifact rather than information. The core message would survive without 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?

An output schema exists so return values need not be re-explained, and with zero input parameters the remaining burden is scope, ordering, cost and failure semantics — all of which are covered. Nothing an agent needs in order 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?

The tool takes zero parameters and schema coverage is 100%, so the description carries no parameter burden and correctly adds none. The returned field names it lists ({question_id, asset, question_label, decision_id, predicted, horizon_end}) are output, not input, 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 defines its domain term explicitly ("open clocks: the pending decisions across the AVAILABLE questions ... and canonical assets") and states the scope, ordering ("soonest horizon_end first") and delivery form ("served as one call"). It is clearly distinguishable from siblings it names, tollbridge_blotter and tollbridge_decision.

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 names the alternatives and the conditions that select them: "For MORE than the canonical three assets use tollbridge_blotter" and "only ask via tollbridge_decision once the question is terminal." It also states the correct workflow (sleep until the soonest horizon_end, re-read) so an agent knows when not to poll.

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, so the safety profile is covered. The description adds genuinely non-redundant behavioral context: the call is free, requires no payment, and falls under an open-data carve-out — exactly the kind of cost/auth fact 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?

Front-loaded with the core identity ('FREE price list for every Tollbridge surface'), followed by the payload contents and the cost caveat. Three compact sentences with little waste, though 'FREE', 'Free per the ... carve-out' and 'No payment required' restate the same point three times.

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

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

An output schema exists, so return shape need not be described, and the description still enumerates the four data categories the agent will receive. The only real gap is the undocumented optional 'payer' parameter, which leaves one invocation decision 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?

There is one parameter, 'payer', with 0% schema description coverage, and the description never mentions it or explains what supplying an address would change about the returned prices. With low coverage the description is expected to compensate, and it does not, leaving the parameter's meaning and optionality unstated.

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 (a price list) and enumerates its contents: per-endpoint USDC prices, subscription plans with effective per-credit rates, booster credit packs, and the credit anchor. No sibling tool in the list covers pricing, so the agent can immediately separate this from the calls/arena/risk 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 positions the tool in the workflow: 'the exact numbers an agent needs before calling any paid tool.' That gives a clear trigger condition. It does not name an alternative or state exclusions, but there is no competing pricing sibling to route away from.

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 mutation + idempotency, and the description adds substantial context beyond them: no-op semantics on repeat calls (granted: false, still returns a readable balance, never a double grant), that no x402 facilitator is needed, and that no payment is required. This is exactly the kind of behavioral detail the schema and annotations cannot carry.

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 key promise (FREE first-run) before details, and every clause is on-topic. The embedded four-step recipe is useful but stretches the definition; slightly tighter phrasing would keep it at 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?

An output schema exists, so return format needn't be documented, yet the description still explains the meaningful granted: false case. Combined with the idempotency and no-payment caveats, 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 coverage is 0%, so the description must compensate. It identifies the single param as a Base address (payer, 0x + 40 hex), adding chain context beyond the raw pattern. It could still say what happens with a malformed or non-Base address, so it stops 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?

States a specific verb (grant) and resource (free taste / entry-tier credits) with exact scope (3 questions, 1000 credits each) and names the mechanism (credit rail, no x402). It is unmistakably distinct from siblings like tollbridge_get_decision or tollbridge_decision.

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 first-run recipe with ordered alternatives: tollbridge_scout → read balance via credit ledger → tollbridge_get_decision/get_resolution → tollbridge_decision only when the latest sentence is terminal. Both the when-to-use and the sequencing of downstream siblings are spelled out.

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 readOnlyHint/openWorldHint/idempotentHint already declaring the safety profile, the description still adds meaningful behavior: the sheet is free, states are derived, 'empty' is data not an error, 'dark' carries the exact blocker, and an unknown/delisted asset yields a typed UNKNOWN_ASSET refusal. It does not describe pagination or return shape, but the output schema covers returns.

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 purpose is front-loaded, but a large fraction of the description is a corrupted 'available set' list with heavy duplication (X05 five times, X06/X07 etc. repeated) that adds no information and contradicts the 'eleven questions' claim. That bloat does not earn its place and dilutes the useful content.

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 an output schema and covering annotations, the state semantics, agent loop, free access, and refusal behavior are adequately covered. Gaps remain: the wallet parameter is unexplained and the internal inconsistency between 'eleven questions' and the S01–S26/X-series list leaves the agent unsure of the actual scope.

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 50%: 'asset' is documented in the schema, but 'wallet' has no description in either the schema or the description. The text says 'for one asset' and mentions needs_wallet inside rows, but never explains what the wallet input does, so the description fails to compensate for the coverage 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 opening states a specific resource and scope: for one asset, the eleven catalog questions (S01…S11) each with a derived state (live/pending/empty/dark) and an ask block. That is a clear verb-less read resource, but the purpose is muddied by the later claim that the available set spans S01–S26 and X05–X09, which contradicts 'eleven questions' and undermines the scope. No sibling (e.g. tollbridge_open_clocks, tollbridge_call) is named to differentiate 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?

The 'AGENT LOOP' gives real conditional guidance: read the sheet, sleep to min(horizon_end) if a row is pending, read the resolution, then ask ONLY rows where ask.allowed == true. However, it never says when to prefer this tool over tollbridge_open_clocks, tollbridge_call, or tollbridge_decision, so usage context is implied rather than routed.

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 this is a non-read-only, non-idempotent, non-destructive mutation. The description goes well beyond that: registration is free but every run bills at settle time against the payer's credit balance via the same paid path as an ask, consent is enforced through acknowledge_spend_cap, and duplicate registration returns a typed conflict rather than a second billing stream.

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

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

Dense but front-loaded — the free-registration/billed-each-run framing comes first, and caps highlight the two hard constraints. It repeats itself slightly, stating the free registration twice ('Registration itself costs nothing' and 'No payment required for the registration itself'), and the DELETE endpoint mention is mildly tangential.

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-parameter, billed, stateful registration tool with an output schema covering returns, nothing material is missing: cost model, spend cap floor, consent flag, subject scoping, uniqueness rule, and the list/stop lifecycle are all covered.

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 17% (just the asset field), so the description carries most of the burden and largely does: it explains the payer's credit balance, the ≥10-window floor on spend_cap_credits, the literal-true requirement on acknowledge_spend_cap, and the wallet requirement for account-scoped questions. It adds little on question_id format or the payer's 0x address pattern, but overall compensates well for the coverage 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 — registering a scheduled question that runs every horizon window — and names its siblings explicitly (tollbridge_stands to list, DELETE /v1/standings/:id to stop). An agent can distinguish it from tollbridge_call (one-off ask) 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 strong prerequisites and lifecycle guidance: cap must cover at least 10 windows at the question's decision tier, acknowledge_spend_cap must be literally true, wallet subject required for account-scoped questions, and one active run per question+subject. It points to tollbridge_stands and the DELETE endpoint for follow-up, though it never explicitly contrasts with the one-off ask path for choosing between 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 cover read-only/idempotent/open-world, but the description adds meaningfully more: it is FREE (no payment required), payer-scoped to the caller's own runs only, sorted newest-first, and it explicitly defines the empty-result semantics and the status enum values (active | paused | spend_cap_reached). These are behavioral traits the annotations do not 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 'FREE' and the core purpose, and the dense first sentence efficiently packs scope plus return fields. Minor redundancy: 'No payment required' restates 'FREE', and 'Strictly personal' restates 'the payer you name', so a little trimming is possible without losing information.

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

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

With only one required parameter and an output schema already present, the description is more than complete: it covers scope, ordering, cost, empty-state behavior, and returned fields. An agent has everything needed to invoke and interpret the result 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 0% (payer has only a hex pattern, no description), so the description must compensate. It does: 'every appointment registered for the payer you name' and 'reads only the named payer's own runs' establish that payer is the owner key scoping the listing. It adds semantic meaning, though it omits the address-format nuance (that lives in the pattern).

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+resource (list the payer's scheduled runs, newest first) and enumerates the returned fields: question, subject, spend cap, credits spent, status, next run time, last decision. It also carves out its scope against siblings with 'no cross-payer listing exists', so an agent can distinguish it from other listing tools 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 context is explicit: it reads your own payer's runs, requires a named payer, and 'an empty list is data (nothing registered), not an error'. The exclusion ('Strictly personal... no cross-payer listing exists') clarifies when this is the wrong tool for cross-payer needs. It stops short of naming the create-side sibling (tollbridge_stand) as the alternative for registering runs.

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/open-world annotations, the description discloses genuinely useful behavior: a paid x402/credit rail, the three ways to supply a payer, that an unpaid call returns a structured payment_required challenge (never fabricated data), and that a refusal refunds the debit. This is real behavioral context that annotations do not carry, though it doesn't describe cost magnitude or latency.

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 sentence 'after paying, poll /v1/resolutions/:id until horizon_end' is duplicated verbatim, and the tool opens with payment boilerplate rather than its purpose. The structure is repetitive and not front-loaded on what the tool does.

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

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

An output schema exists, so return values need not be described, and the payment path is well covered. However, for a 5-parameter tool with nested objects and 20% schema coverage, the missing parameter semantics and absent when-to-use guidance leave the definition only partially 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 only 20%, so the description should compensate, but it only explains 'payer' (Base 0x… address and the x-tollbridge-payer header). The required `asset`, `address`, and the nested `candidate` object are never described, so an agent must infer their meaning entirely from sparse schema fields.

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 the tool returns 'the same account liquidation-proximity distribution as account risk, labelled with the token subject kind', which hints at a token-level risk read. However, the actual purpose is buried under payment and transport boilerplate, and it never distinguishes itself from close siblings like tollbridge_liquidation_risk or tollbridge_transaction_risk.

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 explains how to pay and that you must poll /v1/resolutions/:id until horizon_end, but gives no guidance on when to choose this tool over the 30+ siblings. There are no exclusions or selection criteria, only transactional mechanics.

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 substantial behavior beyond the annotations: paid x402/Scout credit flow with three payment mechanisms, the structured payment_required challenge on unpaid calls, the guarantee of 'never fabricated data', refund-on-refusal, and the resolver tape ('emit and resolver share that tape'). This is well beyond the readOnlyHint/openWorldHint/idempotentHint annotations, though the polling endpoint and horizon_end mechanics remain terse.

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?

'After paying, poll /v1/resolutions/:id until horizon_end' is stated verbatim twice, and the three payment rails are spelled out at length. The decision rules are front-loaded reasonably, but the redundant payment/polling prose bloats a description that leaves core input semantics unexplained.

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

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

An output schema exists, so return values need no explanation, and the payment/decision logic is well covered. However, for a 4-parameter tool with a required nested `candidate` object and a name/description identity mismatch (transaction vs account risk), the definition is not complete enough for an agent to assemble a correct call without guessing.

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 25% — only `asset` carries a schema description. The description clarifies `payer` (a Base 0x address, alternative to the header) but says nothing about `address` or, critically, the required nested `candidate` object (tx_hash, log_index, direction, amount, usd_value, counterparty), leaving the main input shape undocumented in both schema and prose. It does not compensate for the coverage 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 fairly specific computation — Hyperliquid account liquidation proximity, mapped to {allow, review, block} with explicit 5%/15%/5× leverage thresholds — which is more than a tautology. But the identity is muddled: the tool name says 'transaction_risk', the title says 'account risk', and the description talks only about an ACCOUNT's liquidation proximity while the schema requires a `candidate` transaction. No distinction is drawn from sibling tools like tollbridge_liquidation_risk or tollbridge_token_risk.

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

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

There is extensive guidance on HOW to pay and poll, but nothing on when to choose this tool rather than tollbridge_liquidation_risk, tollbridge_token_risk, or tollbridge_wallet_intelligence. No trigger conditions or exclusions for the analysis itself are given; the agent must infer usage from the tool name.

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 readOnly/idempotent/openWorld annotations: discloses the ≤15s cache, that data comes from the venue tape and is never a curated list, that delisted names are dropped, and that quality flips to 'degraded' when a failed refresh serves the last good snapshot. That last detail is exactly the freshness caveat an agent needs.

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

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

Dense but front-loaded: the resource and ranking lead, followed by fields, authority claim, and freshness caveats. Slightly run-on in places, but almost every clause carries a distinct fact with little 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?

Output schema covers return shape, and the description still layers on the non-obvious semantics (freshness, degradation, legality of symbols, cost). For a one-param listing tool, an agent has everything needed to call it 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?

Schema coverage is 0% for the single 'limit' param, so the description must compensate. It supplies the meaningful default ('top 50 by default') but never explains the maximum of 200 or how ranking interacts with limit, leaving half the parameter semantics undocumented.

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 (live perps universe ranked by 24h notional volume) and enumerates the returned fields. The line 'THIS IS THE AUTHORITY on which symbols exist' sharply differentiates it from sibling tools that merely consume symbols, so an agent can pick it without inspecting the schema.

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

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

It implies the use case via 'an asset is legal exactly when it appears here', which tells the agent to consult it for symbol validity, but it never explicitly names an alternative (e.g. market_state, feed) or states when *not* to call it. Usage is inferable rather than spelled out.

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 the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=false), but the description adds substantial non-structured behavior: it is a paid x402 tool, an unpaid call returns a structured payment_required challenge rather than fabricated data, a refusal refunds the debit, refusal codes follow a published taxonomy, and results require polling /v1/resolutions/:id until horizon_end. These are genuine operational facts an agent needs and cannot get from the schema or 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 LIVE set listing is a long, machine-dumped enumeration with obvious duplication (X05 five times, X06 five times, X07 five times, X08 six times, X09 six times) that consumes most of the text without adding selection value. The instruction "After paying, poll /v1/resolutions/:id until horizon_end" is also stated twice verbatim. The opening leads with payment-rail jargon instead of the tool's purpose.

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

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

An output schema exists, so return-value detail is not required, and the payment/refusal behavior is thoroughly covered. What is missing is the semantic content of the result: the description never says what the "profile" read actually contains or how it differs from wallet_state, which is the one thing an agent choosing this tool needs.

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%, so the description carries the burden. It explains `payer` well (a Base 0x… address, suppliable as a tool argument, an x-tollbridge-payer header, or an x402 PAYMENT-SIGNATURE), which is the hardest parameter. But `chain` and `address` are only implied ("Base address") and never explicitly defined as the target of the read.

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

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

It states the resource ("Wallet intel on a Base address") and gestures at a verb ("the profile read"), which partially distinguishes it from the sibling tollbridge_wallet_state. However, "intel" is vague and the follow-on sentence ("the profile/state reads here are the raw surfaces") blurs rather than sharpens the profile-vs-state boundary. An agent cannot confidently tell what data this returns versus wallet_state.

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 does route one class of work elsewhere — S09/S10 account decision questions go through tollbridge_decision, with this tool framed as the "raw surfaces". That is real, if cryptic, usage guidance. But it never states when to choose this over the close siblings tollbridge_wallet_state or tollbridge_get_intelligence, leaving the main selection decision 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 readOnlyHint/openWorldHint annotations, the description discloses a lot: a typed PROVIDER_DOWN refusal with nothing charged, an automatic refund on refusal, a structured payment_required challenge instead of fabricated data, and the payment rail mechanics. This is well above the annotation baseline. The one tension is that readOnlyHint=true sits alongside a tool that debits USDC, which the description never reconciles, though the payment is an access rail rather than a data mutation.

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 text is repetitive and badly ordered: 'after paying, poll /v1/resolutions/:id until horizon_end' appears twice, the payment rail is explained across two separate blocks, and the actual purpose of the tool lands in the middle rather than first. It is not brief and the reader must reassemble the definition.

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

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

An output schema exists, so return values need not be described, and the description covers the unusual payment/refusal behavior and the current unwired state. What is missing is the semantics of the required `address` parameter and any differentiation from the wallet sibling, which an agent needs in order to invoke the right 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 0%, so the description must carry all three parameters, and it only partially does. It explains `payer` well — what it is and the three ways to supply it (tool argument, x-tollbridge-payer header, x402 PAYMENT-SIGNATURE) — which adds real meaning beyond the bare regex in the schema. But `address` (presumably the wallet being inspected) is never defined, and `chain` is only implied by the const and the 'on base' phrasing.

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 does state a concrete resource and output set: 'Wallet state machine on base (WATCHING → ACCUMULATING → HIGH_CONVICTION → DISTRIBUTING → EXITING): current state, since, sample adequacy, 30d net flow and first-seen.' That is specific enough for an agent to know what it returns. However, it never distinguishes itself from the obvious sibling tollbridge_wallet_intelligence, and the purpose is buried behind payment and DEFERRED boilerplate rather than front-loaded.

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 post-call flow ('after paying, poll /v1/resolutions/:id until horizon_end') and a critical operational caveat that the indexer is unwired and calls currently refuse, which is real when-to-use guidance. But it gives no condition for choosing this over tollbridge_wallet_intelligence or the other wallet tools, and the DEFERRED note makes the tool effectively unusable with no stated alternative.

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