Tickerz

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so safety and idempotency are covered. The description adds useful context: forecasts are only listed after a question closes, the Arena number is frozen at close and never official, and points are calculated without money or prizes. However, it doesn't describe pagination, rate limits, or response format beyond what's implied, and some statements (e.g., 'forecasts are listed only after it closes') are behavioral constraints already implied by the read-only, closed-world nature.

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 single dense paragraph that packs multiple concepts (current questions, recent results, standings, points calculation, id behavior, disclaimers) without clear separation or front-loading. It is hard to parse quickly and includes redundant details (e.g., exact points formula, 'Same data as GET /api/arena' which may be unnecessary for an agent). It lacks structure and prioritization.

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 one optional parameter and no output schema, the description provides enough context to know the tool returns Arena data, including questions, recent results, and standings. However, it does not clarify the exact response shape or what fields are returned, and the dense packing makes it incomplete for an agent trying to decide if this tool returns the needed data versus using get_question or open_questions. It covers the domain but leaves gaps in usage and output structure.

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

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

Schema coverage is 100%; the single optional 'id' parameter is fully described in the schema. The description adds context about what happens with id ('with id, one question: forecasts are listed only after it closes'), which clarifies the id's effect but doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with 'The Arena: predict the number an index lands on,' which does state a specific purpose and distinguishes the tool from siblings like open_questions or get_question by positioning it as a hub for Arena data. However, it immediately dives into mechanics (index, forecast count, close time) without clearly stating the tool's primary function: returning Arena state (current questions, recent results, standings). The name 'arena' and lack of a clean verb+resource opener leave the purpose somewhat buried.

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 guidance, no mention of alternatives like get_question (for a single question) or open_questions (for active questions). The description says it returns 'the same data as GET /api/arena and GET /api/arena/question/{id}', which implies it can be used for both, but does not clarify when to prefer this tool over those siblings. No exclusions or conditions are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered; the description adds genuinely new behavioral context: venue links are 'plain unpaid links checked nightly', scores_30d is a downsampled tick feed with explicit cadences, and driver/reason are null when no event is open. It omits auth, rate limits and pagination, so not a 5.

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

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

It is front-loaded correctly with the 'Use when' trigger, and most clauses carry load-bearing information. But it reads as one dense wall of run-on sentences with the schema-shaped detail (sampling cadence, deprecated aliases) interleaved, which makes it harder to scan than it needs to be.

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

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

With no output schema, the description correctly shoulders the burden of describing the return payload, including edge cases (null driver), field equivalences (latest.score = last scores_30d point), and a deprecation horizon for heat_7d/peak_heat. Coverage of error conditions and response envelope is missing, keeping it at 4.

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% for the single symbol parameter, so the schema already carries the semantics. The description only implies the domain (crypto and stocks both accepted) without adding format or constraint detail, so the baseline 3 applies.

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

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

The description states a specific verb and resource with unusual precision: 'One asset in depth: latest snapshot, scores_30d, the open event and the 10 most recent past events ... and venues.' An agent can tell exactly what it retrieves. It stops short of naming a sibling tool to distinguish itself from, so it lands at 4 rather than 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?

'Use when someone asks about one coin or stock' followed by concrete triggers ('why $X is moving', 'whether its volume is unusual', 'how its past spikes turned out') gives clear selection context. There is no explicit when-not-to-use clause and no alternative tool named, which keeps it below 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?

With annotations covering the safety profile (readOnly, idempotent), the description still adds substantial behavior: the dataset size and provenance, the matching criteria, the 1/7/30-day output windows, and the specific null-with-reason cases (stocks, quiet days, small/dominated/indistinguishable groups). This is exactly the kind of context annotations cannot convey.

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

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

The use-case trigger is front-loaded, which is good, but the second sentence ('What historically happened after a move like this asset's current one.') repeats the first, and the methodology sentence is long enough to obscure the operative facts. Some consolidation would help.

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

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

There is no output schema, so the description must (and does) explain the return shape: median, spread, and share beating Bitcoin over three horizons versus an ordinary day, plus the null-and-reason paths. Nothing needed to interpret a response is missing.

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

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

Only one parameter (symbol) and schema description coverage is 100%, so the schema already carries the semantics. The description adds no syntax or format guidance for the symbol beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific analytical operation: what historically happened after a move like this asset's current one, computed from 3,213 attention spikes. It's clearly distinct from siblings like arena, asset, or methodology. It loses a point only because the opening clause and the follow-up sentence restate the same idea rather than sharpening 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?

Explicit trigger: 'Use when someone asks what usually happens after a spike like the one an asset shows today.' It also describes failure conditions (stocks return null, quieter days return null). It does not name a sibling alternative for related questions, so it stops short of full routing guidance.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), it discloses non-obvious traits: assets are mixed crypto+equity sorted by score, breadth counts crypto only regardless of class, score is null for assets still building a 14-day baseline, heat/heat_1h are deprecated aliases kept until 2026-12-31, and no prices are returned due to vendor licensing.

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

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

Front-loaded with the use case before the field details, and every clause carries information given there is no output schema. It is dense and parenthetical-heavy, which slightly hurts readability, but nothing is truly redundant.

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

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

With no output schema, the description must carry return-value semantics, and it does: score/score_1h scale, vol_mult definition, updated_at, breadth bands (lone/mid/crowd), and the null-score rule. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% so the enum is already documented, but the description adds real meaning: the default (omit for every asset), the fact that mixing happens by default, and that breadth ignores the class filter. It goes beyond the schema baseline.

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

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

The description opens with concrete trigger scenarios (unusual crypto/US stock activity, coins far above normal volume) and then names the resource precisely: 'Current Tickerz Terminal: all tracked assets with the 24h move...'. It is unmistakably a market-anomaly board, distinct from asset, arena, or get_index siblings.

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

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

Explicit when-to-use is given via the opening scenarios, plus guidance on the class filter ('send class crypto or equity to get one kind, or filter on each asset's class'). It does not name alternative tools or state when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld false. The description adds extensive behavioral context beyond that: the full response shape, partial_day semantics, proof statuses and timing (stamped after 12:00 UTC), and null handling for restricted source terms. This is rich 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?

The purpose is front-loaded, and no sentence is mere filler given the absence of an output schema. Still, the text is a dense single paragraph with long, semicolon-heavy sentences, which makes it harder to scan than an ideally structured definition.

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

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

With no output schema, the description must carry the full burden of explaining return values, and it does: periods, bands, z-scores, first_print, seal, proof details, statuses, and timing. It also covers edge cases like partial days and nulls, so an agent has what it needs to interpret results correctly.

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

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

Schema coverage is 100% and only one parameter exists, so the baseline is 3. The description adds value by enumerating all valid tickers and tying the ticker to list_indices, which goes beyond the schema's generic example.

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

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

The description opens with a specific verb-and-resource purpose: retrieving history, rules, source and proof for one index, and it names list_indices as the source of valid tickers. It clearly distinguishes this single-index lookup from the sibling list_indices, so an agent can select it without opening other 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?

It explicitly says to use it for one index named by list_indices and enumerates valid tickers, establishing the context. However, it does not spell out when not to use it or contrast it with other siblings beyond the ticker-source relationship, so it falls short of a full 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 the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely useful behavior beyond that: crowd split only appears once answers close, and the outcome is 'the first stored Activity score at or after the resolve time; void when none lands within 3 hours'. It does not cover auth or rate-limit behavior, keeping it short of a 5.

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

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

It is front-loaded correctly ('One question by id...'), but the remainder is a dense run-on paragraph mixing payload fields, OpenTimestamps mechanics, and a REST-equivalence note. Much of the content is justified by the absent output schema, yet the phrasing is packed enough to impede fast parsing.

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

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

With no output schema, the description carries the full burden of describing the return payload, and it does so thoroughly: statement, nulls, answer, crowd split, outcome/void rule, right/wrong, and the proofs[] structure with the digest equality check. Only minor details like auth or error behavior are 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?

There is a single parameter with 100% schema description coverage, so the schema already documents that id is a uuid sourced from open_questions. The description adds only the trivial 'by id' framing, so baseline 3 is correct.

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

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

States a specific verb+resource+scope: 'One question by id, open or resolved', which an agent can distinguish from the sibling list tool open_questions. However, it never names open_questions or any alternative explicitly, so the differentiation is left to inference.

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

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

Usage is implied rather than stated: the id must come from open_questions or the REST list endpoint (that hint actually lives in the schema, not the description). There is no explicit when-to-use/when-not or named alternative, so an agent must infer the lookup-by-id workflow.

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 are present (read-only, idempotent, non-destructive, closed-world), so the safety bar is lower. The description still adds substantial behavioral context: Bitcoin anchoring for immutability, late-landing sources, provisional partial days, the distinction between latest/latest_complete, and the fact that some sources serve score/bands only. These are real traits 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?

The description is very long and front-loads a list of concrete questions (pump.fun, Kalshi, Polymarket, Hugging Face, Chicago crime, x402) before stating what the tool actually does. Key routing details like 'Same data as GET /api/indices' and the latest/latest_complete distinction are buried, making it hard to scan. Many sentences are informative but the structure 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?

Given zero parameters, no output schema, and rich annotations, the description is functionally complete in coverage of concepts, anchoring, and provisional-day behavior. But it is disorganized and omits a clear statement of return structure at a glance; an agent must read the entire paragraph to know the list returns all indexes with period/value/band.

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

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

There are zero parameters, so the baseline is 4. The description explains the shape of the returned periods (period, value, band, p25/p75 for WAGE, partial_day flags), which is useful given no output schema, though it concerns output rather than parameters.

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

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

The description opens with a long list of example questions and only later explains that Tickerz reads each as a daily index against its own normal, on-chain in Bitcoin. The core purpose (list all Tickerz indexes) is buried and never stated as a clear verb+resource. A sibling get_index likely serves individual indexes, but the plural scope of list_indices is not stated until 'Same data as GET /api/indices' and even then only implicitly.

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 opening 'Use when...' plus examples implies usage, and the later note about latest_complete versus latest gives some selection guidance between periods. However, it never states when to use list_indices instead of get_index, methodology, or other siblings, and the example-driven framing substitutes for explicit when-to-use rules.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining that the response is Markdown text and that structuredContent contains the same text as JSON with model, url, markdown, and section headings, which is useful 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?

The description is concise and front-loaded: the first sentence states the tool's purpose and source, the second clarifies no proprietary parameters, and the third describes the output format. Each sentence earns its place without unnecessary detail.

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

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

For a no-parameter, read-only tool, the description is complete. It covers what the tool returns, the serialization structure of the output, and the public source URL. The absence of an output schema is mitigated by the explicit structuredContent 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?

The input schema has zero parameters, so the baseline is 4. The description explicitly says 'No proprietary parameters,' confirming there are no hidden inputs and that the tool is parameter-free.

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

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

The description clearly identifies the resource (Public Sigma-1 methodology) and the produced result (text), and distinguishes it from the sibling tools by its standalone methodology focus. However, it lacks an explicit verb like 'retrieve' or 'get', and does not directly contrast itself with the sibling 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?

The description provides no guidance about when to use this tool versus alternatives such as open_questions or get_question. The only contextual clue is the title and the standalone nature of the description, which is insufficient for an agent deciding among siblings.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavioral context beyond that: accepting_answers is true until 4 hours after open, the crowd split stays null until then, and the three nulls are frozen at creation. It omits pagination/volume limits, so not a 5.

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

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

The purpose is front-loaded in the first clause, but the body is a single dense run-on paragraph packed with domain-specific terms. Every sentence carries information, yet the wall-of-text structure hurts readability without a clear field-by-field breakdown.

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

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

With no output schema, the description must carry the return-value burden, and it does explain the returned fields (score, volume multiple, three nulls, Tickerz answer, calibration hit rates). It is highly complete for a complex domain tool, missing only edge cases like empty/open-empty states.

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% for the single symbol parameter, so the schema already documents it as an optional ticker. The description's 'Optional symbol filter' adds no syntax or format detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

The opening clause states a specific resource and state: the referee's questions still awaiting answers, explicitly mapped to GET /api/questions?state=open. It is distinguishable from the single-question sibling get_question, though heavy domain jargon ('referee', 'Tickerz') slightly obscures the plain 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 notes an optional symbol filter and that it is 'not advice', but gives no explicit when-to-use or when-not guidance and never routes the agent to alternatives like get_question, base_rate or board for related data. Usage must be inferred from the 'still waiting on their answer' phrasing.

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, non-destructive, idempotent, closed-world. The description adds value beyond that: receipts become null until due, cursor semantics via next_before/next_before_id, and a deprecation horizon (peak_heat until 2026-12-31). Strong added context despite annotations doing the safety profile.

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?

A single dense paragraph mixing return-shape details, cursor semantics, filter behavior, deprecation notes, and cross-endpoint references. Front-loaded usage is good, but the wall of clauses about null receipts and cursor edge cases is hard to parse; it should be broken into bullets or short sections.

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

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

No output schema, yet the description enumerates the return fields (receipts, benchmark, score_at_open, peak_score, driver, proof_url, next_before/next_before_id, peak_heat alias) and cursor contract, so an agent can consume the response. Would reach 5 with clearer field/key naming for the proofs rows.

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 goes further, explaining interaction between 'before' and 'before_id' (skip vs. include same-time events) and clarifying that 'symbol' filters in the query so 'limit' counts only that ticker. Adds real semantic value on top of the schema.

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

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

States a specific verb+resource: closes events with their receipts, newest first. Distinguishes from siblings like arena, base_rate, board by describing a concrete track-record surface with named fields. An agent can tell what this returns without opening anything.

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?

Opens with an explicit when-to-use trigger ('Use when someone asks how past attention spikes turned out, or wants a track record they can check, losses included') and mentions 'Same store as GET /api/receipts'. Does not name an alternative sibling to use instead, so it falls short of 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?

With annotations covering only mutation/idempotency/open-world/destructive hints, the description adds rich behavioral context: handle claiming, the one-time handle_key secret and address-change behavior, one forecast per handle, latest-before-close semantics, grading formulas, hidden forecasts, Referee answer limits, OpenTimestamps recording, agent-name handling, and explicit 'no login, no prizes, no money' caveats. It does not contradict 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 description is well structured with numbered modes and a 'Both:' section, but it is long and includes operational details such as grading formulas, standings ranking, and nulls that are not strictly needed to invoke the tool correctly. For a complex dual-mode tool some length is justified, but several sentences could be trimmed without harming selection or invocation.

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 tool's complexity, 8 parameters, 100% schema coverage, annotations, and no output schema, the description is complete for an agent to call it correctly. It covers both modes, parameter dependencies, per-caller limits, identity/handle behavior, closing rules, and return-ish signals like handle_key and already_answered true.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds conditional parameter relationships beyond the schema: it groups parameters into Arena vs. Referee sets, explains that handle_key must be sent on later forecasts under the same handle, and clarifies ticker as an alternative to question_id. The schema already defines each field well, so this is a strong supplement rather than a replacement.

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

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

The description opens by stating the tool submits forecasts and immediately splits the task into two specific modes: Arena numeric forecasts and Referee attention questions. It identifies the required resources (question_id/ticker/handle/value vs. question_id/answer/probability) and distinguishes the two modes clearly, so an agent can tell what the tool does without opening the schema.

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

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

It explicitly routes usage by question type: Arena forecasts use the arena tool or a ticker, while Referee questions use a uuid from open_questions. It also names sibling tools (arena, open_questions) as sources and gives concrete when-to-use conditions for each mode, leaving little to inference.

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