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?

Goes well beyond the readOnly/idempotent annotations: it declares cost ("FREE", "No payment required"), determinism ("arithmetic — never an opinion"), failure semantics ("a refusal is not experience", "an explicit null with a blocker"), and the pricing guarantee that the listed price is what will be charged. That is exactly the behavioral context 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?

The key value proposition ("WHAT EARNS THE MOST XP NEXT") is front-loaded and each clause carries a distinct rule. The single long paragraph of semicolon-chained prohibitions is dense and could be split into bullets for faster scanning.

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

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

Covers the response shape (per-item executable target or explicit null with blocker), the wait path, the auxiliary outputs (agent-track declaration, XP still available this window), and cost. With an output schema present, nothing an agent needs before calling 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?

Only one parameter, payer, and the schema has 0% description coverage, so the description must compensate. "Name your payer address" does clarify that payer is a wallet address, but gives no format, chain, or case example — minimal compensation for an undocumented required field.

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 outcome ("the OPEN quests for your wallet ranked deterministically by their XP reward and how little remains") with concrete follow-on fields. It never references the closest sibling, tollbridge_arena_quests, so an agent must infer the distinction between a ranked recommendation feed and a plain quest listing.

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

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

Gives explicit operating context: "If action is wait, sleep until window_end; do not run a decision while a window is in progress; do not re-run a question to farm experience." These are clear when/when-not rules for acting on the result, though it does not route the agent to or away from any specific sibling tool.

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?

Beyond the annotations (readOnly/openWorld/idempotent=false) it discloses a lot: x402 exact USDC on Base or Scout credits, three accepted payer mechanisms, a structured payment_required challenge when unpaid, never-fabricated data, refund on refusal, typed 404 for unknown/delisted symbols, and the need to poll /v1/resolutions/:id until horizon_end. It does not cover rate limits or how many calls a debit buys. Note the tension: a tool that debits credits is not obviously side-effect free, though the underlying signal read is non-mutating.

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 enormous and dominated by a heavily duplicated instrument list (S01/S05 repeated, X05 five times, X06–X09 six times each), with no reader benefit. The first sentence is cryptic ('x402 exact USDC Base · after paying, poll ...') and pushes the actual purpose past the noise. Most sentences do not earn their place.

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

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

For a paid, multi-step decision tool with an output schema available, it does cover payment rails, refusal/refund semantics, error typing and the post-payment polling loop, which is the hard part. Gaps remain on `question_version` semantics and on how it relates to the sibling ask/get_decision tools, and the qualifier list is so corrupted it is unreliable as an availability reference.

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 it partially does: it expands `payer` (0x Base address, credit rail, x-tollbridge-payer header, x402 PAYMENT-SIGNATURE), clarifies `asset` accepts any universe symbol, and maps question_id families (S01–S26, X05–X09) to the data each reads. But the mapping is drowned in duplicated, partly garbled entries (X05 listed five times, X06–X09 repeated), and `question_version` is never explained.

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 leading sentence states a concrete verb+resource: ask a catalog signal through the decision engine for an asset on base, returning probability, confidence, policy verdict, horizons and provenance. It also names which inputs are askable and routes the caller to tollbridge_universe and tollbridge_pricing. It stops short of explicitly distinguishing itself from near-neighbours such as tollbridge_call, tollbridge_calls or tollbridge_get_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 describes an agent loop (get latest → get resolution → ask the NEXT dated sentence) and notes that blocked questions S02/S03/S04 return out_of_scope instead of a gradeless probability, which is genuine when/when-not context. However it never contrasts itself with the obvious alternative ask-tools in the sibling list, leaving the choice 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=false, idempotent=true, destructive=false, and the description adds substantially: one export debits billing.export.asset_period, failed generation reverses the debit, refusal refunds and carries no rows, unpaid calls return a structured payment_required challenge with no fabricated data, and other payers' private subjects are redacted to null. This is rich behavioral context beyond 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?

It leads with payment mechanics rather than the core purpose, and repeats 'After paying, poll /v1/resolutions/:id until horizon_end' and the PAID/USDC framing twice. Dense and information-rich, but several clauses could be cut without loss, so it is not well 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?

For a paid, billing-affecting export tool an output schema already exists, so return values need not be described; the description instead covers pricing, payment rails, idempotency/replay, refunds, redaction, and challenge-on-unpaid behavior. An agent has everything needed to invoke it correctly.

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

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

With 0% schema description coverage the description must carry the load, and it explains payer (tool arg, x-tollbridge-payer header, or x402 PAYMENT-SIGNATURE), scope (asset symbol vs question id), subject, and format (CSV/JSONL). It only indirectly implies the from/to window via 'one UTC calendar month' and 'oversized window', leaving the two date-time parameters unlabeled.

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: export the decision history for one subject over one UTC calendar month as CSV or JSONL, with an explicit field list (claim, distribution/probability, confidence, hashes, decided_at, horizon, outcome). An agent can distinguish it from the sibling read tools (tollbridge_decision, tollbridge_get_decision) without opening the schema.

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

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

Gives clear operational context: it is a paid add-on, the same subject+month is a typed replay that is never re-charged, an oversized window is refused and should be narrowed, and exact price comes from tollbridge_pricing. It does not, however, route the agent to or away from specific sibling tools for the same data, so it stops short of explicit alternatives/exclusions.

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

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

Annotations already declare 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?

Annotations only declare readOnly/openWorld/non-idempotent, so the description carries heavy extra weight and mostly delivers: it discloses the paid x402 requirement, that unpaid calls return a structured payment_required challenge rather than fabricated data, that refusals refund the debit, and that resolution requires polling until horizon_end. It also clarifies the output is a policy verdict, not a trade. It slightly muddies the picture by mixing in S07 persistence product detail that belongs to a different instrument.

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 entire description is one dense run-on paragraph, and it literally repeats 'After paying, poll /v1/resolutions/:id until horizon_end' twice. It also front-loads payment rails ahead of the scan's purpose, so the useful content is buried and the text does not earn its length.

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 explained, and the description adequately covers payment and polling. However, for a tool this complex it omits when to prefer it over sibling decision tools and reads partly as product marketing, leaving the selection decision under-supported.

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 explain the single parameter, and it does: payer is a Base address 0x…, passable as a tool argument, via the x-tollbridge-payer header, or via an x402 PAYMENT-SIGNATURE. That fully compensates for the empty schema, though the exact format constraint is only implied by '0x…'.

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

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

States a specific verb and resource: a 'funding-anomaly scan across BTC/ETH/SOL' returning per-asset funding (bps), basis (bps), and the S06 engine decision. That is concrete and distinguishable from generic siblings, though it never positions itself against tollbridge_decision or tollbridge_get_decision, which appear to overlap.

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?

Most guidance is about payment mechanics (how to pay, which rail, what an unpaid call returns) rather than when to choose this scan over sibling analysis tools. It does note that current USDC should come from tollbridge_pricing, which is a genuine routing hint, but the analytical 'use this when...' condition is left implicit.

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?

Richly exceeds the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false). It discloses billing behavior (debits the add-on, 30-day window, no double charge), idempotent replay semantics, that delivery truth lives in the attempt record and not registration, URL validation (loopback/private/metadata refused), one-time secret exposure, and refund-on-refusal. This is exactly the extra context 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?

The description is a dense wall of text that leads with payment boilerplate before the actual purpose, and repeats 'after paying, poll /v1/resolutions/:id until horizon_end' verbatim twice. Substantive content is present, but significant redundancy and poor front-loading hurt efficiency.

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 need not be explained, and the description still covers payment rails, refunds, validation behavior, secret handling, and the post-registration polling step. An agent has everything required to invoke and sequence this tool correctly.

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

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

Schema coverage is 0%, so the description must compensate: it defines `url` as a public http(s) URL validated at registration and explains `payer` (Base 0x… address) plus alternative transport via the x-tollbridge-payer header or PAYMENT-SIGNATURE. Both parameters gain meaning beyond the raw schema, though exact URL constraints are only loosely specified.

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: 'register an outcome hook endpoint: a public http(s) URL that Tollbridge POSTs to when one of the payer's decisions settles (realized or unresolvable).' No sibling competes (it's the only hook tool), and the trigger condition is named. However, the purpose is buried behind leading payment-protocol boilerplate, weakening the front-loading of the purpose 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?

Gives workflow guidance ('after paying, poll /v1/resolutions/:id until horizon_end') and idempotency context (re-registering inside the window replays honestly), which implies when registration matters. But it never contrasts this tool against alternatives and leaves the register-then-poll relationship implicit rather than as explicit when/when-not guidance.

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

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

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?

Richly discloses behavior beyond the annotations: the paid x402/credit rail, the payer argument or x-tollbridge-payer header, the requirement to poll /v1/resolutions/:id until horizon_end, the refund-on-refusal semantics, and the guarantee that it never fabricates a probability. The annotations themselves (readOnlyHint=true, openWorldHint=true, idempotentHint=false) are consistent with an external read that is not idempotent, though the readOnlyHint sits in mild tension with a call that debits a USDC/credit balance.

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?

Badly front-loaded: the critical 'NOT AVAILABLE YET' gate comes after a payment/logistics run-on, and 'After paying, poll /v1/resolutions/:id until horizon_end' is repeated verbatim later in the same paragraph. Refusal taxonomy is restated twice (inline and as a parenthetical list), and the x402/credit rail is re-described in three forms, all of which push the actual purpose out of view.

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

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

Given the complexity (paid, gated behind 24 hourly observations, refund semantics) the description covers availability, prerequisites, payment mechanics, and refusal codes, and an output schema exists so return values need not be spelled out. What is missing is any statement of what a successful (non-refusal) response actually contains, leaving the agent without a positive-path expectation.

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

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

Schema coverage is only 50% (payer has no schema description), so the description must compensate — and it does, fully specifying payer as a Base 0x… address or the x-tollbridge-payer header fallback. For asset it adds scope ('any symbol the venue universe lists... not only BTC/ETH/SOL') and routes to tollbridge_universe, adding meaning beyond the regex/length constraints.

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 identifies a specific resource — the market-wide liquidation tape for a venue asset — and explicitly distinguishes it from wallet-level data ('liquidations appear only as a marker on per-wallet fills... a single wallet is not the book'). However, it never states in plain terms what the tool returns (a liquidation-risk probability over a horizon), and the opening line is payment logistics rather than purpose, so the agent must reconstruct the intent from 'S02' and the refusal-code framing.

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 concrete enabling conditions (operator mounts a Hyperliquid node trade stream at NODE_TRADES_DIR, sets LIQUIDATION_SOURCE=node_trades, and 24 hourly observations must be owned before S02 leaves the default surface) and the consequence when not met (typed refusal, debit refunded). It does not point to an alternative tool to use for liquidation questions when the tape is unavailable, which keeps it short of a 5.

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

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

Annotations already 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?

Annotations cover only the safety profile (readOnlyHint, openWorldHint, idempotentHint=false). The description adds substantial context the annotations cannot convey: the x402 USDC Base payment requirement, the three ways to supply the payer, the structured payment_required challenge on unpaid calls, the no-fabricated-data guarantee, and the refund-on-refusal policy. It loses a point only for not clarifying whether the polling endpoint implies async/partial results or how long horizon_end takes.

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' appears verbatim twice in the description, which is pure redundancy. The payment alternatives are also listed three times over, and the dense x402/rail jargon crowds out the actual purpose, so the payload is not 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 values need not be described, and the paid-call lifecycle is well covered. Against a 5-parameter tool with nested required objects and only 20% schema coverage, though, the description omits the shape and meaning of most required inputs, leaving the agent under-equipped to build a valid call.

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

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

Schema description coverage is only 20% across 5 parameters with a nested candidate object, so the description must compensate. It does explain 'payer' precisely (Base address 0x…, plus the header alternative), but says nothing about the required 'asset', 'address', or the structured 'candidate' object, leaving the majority of low-coverage parameters 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 it returns a liquidation-proximity distribution as 'the same account liquidation-proximity distribution as account risk, labelled with the token subject kind', which does distinguish it from account-risk siblings by subject kind. However the phrasing is dense jargon and never plainly says the action is 'retrieve token risk', so an agent must parse two layers of internal vocabulary to grasp the purpose.

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 choice condition (token subject vs account subject) and points to tollbridge_pricing for exact USDC, which is useful routing. But there is no explicit when-to-use vs when-not guidance, no statement of what the tool is unsuited for, and the payer/payment conditions are mechanics rather than 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?

Despite readOnly/openWorld annotations, the description discloses substantial behavior the annotations do not: the paid x402 USDC-on-Base model, three payer-passing options, the poll /v1/resolutions/:id until horizon_end flow, that an unpaid call returns a structured payment_required challenge (never fabricated data), and that a refusal refunds the debit. This is exactly the auth/payment/side-effect context 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?

The sentence 'After paying, poll /v1/resolutions/:id until horizon_end.' appears verbatim twice, and payment-rail mechanics are front-loaded ahead of the tool's actual purpose, forcing the reader past three clauses of billing before learning what is being assessed. Content is valuable but poorly ordered and visibly duplicated.

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 described, and the payment/polling flow is well covered. But for a tool with a required nested `candidate` object and an `address` parameter, the description omits what those inputs represent, which is a real completeness gap for a high-complexity, paid call.

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

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

Schema description coverage is only 25% (only `asset` is documented in the schema), so the description carries the burden — and it explains only `payer` (a Base 0x… address). It never explains `address` (presumably the account to assess) or the required nested `candidate` object (tx_hash, log_index, direction, amount, etc.), leaving two required parameters semantically opaque.

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

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

The description names a concrete computation — the assessed ACCOUNT's liquidation proximity classified into {allow, review, block} with explicit thresholds (block ≤5%, review ≤15% or ≥5× leverage) read from clearinghouseState. That is specific and actionable. However, it never distinguishes this from the near-identical sibling tollbridge_liquidation_risk, and the name/title ('transaction_risk'/'account risk') mismatch adds avoidable ambiguity.

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 implied through the threshold logic and the pointer that exact USDC comes from tollbridge_pricing, but there is no explicit when-to-use statement and no routing against alternatives such as tollbridge_liquidation_risk or tollbridge_wallet_intelligence. The agent must infer the use case.

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 only the safety profile (readOnly/openWorld/idempotent), and the description adds substantial behavior beyond them: x402 exact-USDC payment on Base, the alternative Scout credit rail, payer passed as argument/header/PAYMENT-SIGNATURE, polling /v1/resolutions/:id until horizon_end, unpaid calls returning a structured payment_required challenge instead of fabricated data, refusal refunding the debit, and the published refusal-code taxonomy. This is exactly the kind of non-obvious operational context 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?

The text is dense and poorly front-loaded: it opens with payment mechanics rather than the tool's purpose. The "LIVE set" enumeration is bloated with verbatim duplicates (X05 five times, X06 five times, X07 five times, etc.), which is pure noise, and the payment sentence is repeated nearly verbatim later in the description.

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

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

An output schema exists, so return values need not be described, and the description still covers payment, the credit rail, refusal handling/refunds, and routing to tollbridge_decision. What is missing is a clean statement of how this read differs from the sibling state/intelligence reads; the bloat competes with the useful content.

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, and it does for `payer`: it explains the value is a Base 0x… address and three distinct ways to supply it. `chain` (const base) and `address` are only implicitly covered by "on a Base address," which is adequate but less explicit than the payer treatment.

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 core purpose is stated specifically: "Wallet intel on a Base address: the profile read," which is a clear verb+resource. It partially differentiates siblings by routing decision questions to tollbridge_decision, but it never cleanly separates this tool from tollbridge_wallet_state (it lumps them together as "the profile/state reads"). The purpose sentence is also buried behind payment boilerplate, blunting first-glance 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?

It does give routing guidance for one case: S09/S10 account decision questions should go through tollbridge_decision with a wallet subject, and "the profile/state reads here are the raw surfaces." However there is no explicit statement of when to use this tool versus tollbridge_wallet_state or tollbridge_get_intelligence, and no exclusions. Usage is implied 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 only cover readOnly/openWorld/idempotency, yet the description discloses an unusual amount beyond them: the indexer is unwired, calls refuse with a typed PROVIDER_DOWN and charge nothing, a refusal refunds the debit, an unpaid call returns a payment_required challenge rather than fabricated data, and the current price must be read from tollbridge_pricing. These are exactly the failure/payment behaviors an agent needs. No contradiction with readOnlyHint (paying for a read does not mutate state).

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 payment instruction is duplicated nearly verbatim at the opening and again in the PAID paragraph ('after paying, poll /v1/resolutions/:id until horizon_end' appears twice). The most decision-relevant fact — that the tool is DEFERRED and refuses all calls in v1 — sits mid-paragraph rather than being front-loaded, and the actual purpose arrives after the payment boilerplate.

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 prose, and the description still covers payment rails, refusal semantics, refunds, and the deferred indexer state — enough for an agent to attempt the call correctly and interpret a refusal. The remaining hole is sibling differentiation against tollbridge_wallet_intelligence.

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 full load. It does well on `payer` — states it is a Base 0x… address, that it can be passed as a tool argument, as an `x-tollbridge-payer` HTTP header, or via an x402 PAYMENT-SIGNATURE. But `address` (the wallet being analyzed) and `chain` get no explanation at all, leaving the central parameter semantics ambiguous.

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 core sentence is specific: a wallet state machine on Base with named states (WATCHING → ACCUMULATING → HIGH_CONVICTION → DISTRIBUTING → EXITING) and named outputs (current state, since, sample adequacy, 30d net flow, first-seen). That is far beyond a tautology. However the purpose is buried behind payment boilerplate and the description never distinguishes this tool from the sibling tollbridge_wallet_intelligence, so an agent must guess which wallet tool to pick.

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 real operational context — pay via x402/credits, then poll /v1/resolutions/:id until horizon_end, and it warns that in v1 calls refuse typed (PROVIDER_DOWN). But it offers no when-to-use-vs-tollbridge_wallet_intelligence routing guidance, which is the main selection decision an agent faces here.

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