Vatic prediction markets

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

No annotations are supplied, so the description carries the full burden, and it discloses only two things: cancellation is free and a manage_token is needed. For a mutation tool it says nothing about whether cancellation is reversible, what happens to the alert's data or history, or whether the token can be reused.

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 short sentences with the core action front-loaded and no wasted filler. The second sentence is terse to the point of being cryptic ("Free" is ambiguous — no charge, or no rate limit?), which keeps it out of the top band.

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

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

This is a mutation tool with no annotations, no output schema, and 0% parameter coverage, which is the combination that demands the most descriptive support. The description leaves the agent guessing about reversibility, post-cancel state, and the meaning of `id`.

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 both parameters are undocumented in the schema. The phrase "its manage_token" does clarify that the `token` parameter is the manage_token issued at subscribe time, which is genuine added meaning, but the required `id` parameter is never explained at all.

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

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

"Cancel your alert" gives a specific verb and resource, which is enough to distinguish it from siblings like alert_subscribe and alert_status by name alone. It stops short of 5 because scope details (does it delete the alert or just stop delivery?) are absent.

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 never states when to call this versus alternatives — nobody is told to use alert_status to find the alert first, or that cancelling is the counterpart to alert_subscribe. The only guidance is the implicit "your alert" ownership framing.

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

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

The description explicitly states that the tool is 'Free,' which is a useful behavioral constraint (cost) not present in the structured fields. This adds moderate value beyond the generic data retrieval context.

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

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

The description is short and avoids unnecessary jargon, but it is somewhat fragmented across two sentences, and both sentences provide only minimal operational 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?

Given the tool's low coverage and lack of an output schema, the definition is incomplete. It does not specify what fields are returned in the delivery history or how the status is presented.

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 provide deep context. It fails to define the role of the 'token' or specify any format constraints beyond what the schema already mandates for the 'id' 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?

The description states the goal is to see 'Your alert and its last deliveries,' which implies retrieving status and history. However, it lacks a specific verb (e.g., 'retrieves' or 'lists'), making the purpose slightly vague regarding the exact action.

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 only hints at a requirement ('Free with its manage_token'), indicating a dependency. It fails to provide explicit guidance on when to use this tool versus other alert-related tools in the ecosystem.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the 30-day lifetime, that the webhook is signed with a secret issued once, that a 2xx test ping is required or the caller is not charged, and the $0.10 x402/USDC cost. Undisclosed behaviors remain — delivery retry policy, what happens on a failed ping response body, and the mechanism for later retrieving or rotating the signing secret.

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, then compact per-type clauses, then commercial terms. Dense but every sentence carries information; the parenthetical-heavy style makes it slightly run-on but nothing is 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?

Six parameters, no annotations, no output schema, and two enums the schema barely documents. The description covers the important behavioral and cost surface but leaves real gaps for a stateful, paid subscription tool: how the signing secret is delivered, whether multiple subscriptions can coexist, and how to stop an alert. Adequate but not complete.

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

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

Schema description coverage is only 17%, so the description must compensate. It explains the meaning of market_id and threshold (points, default 15) and keyword/category for new_market, plus that webhook_url must be https — that is genuine added meaning. It omits the documented threshold bounds (5-50), keyword length limits, and assigns no semantics to the 'type' discriminator itself.

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

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

Opens with a specific verb+resource ('Webhook alerts for 30 days') and then enumerates the two subscription types (market_move, new_market) with what each triggers on. An agent can tell this creates a persistent alert subscription, distinct from alert_cancel/alert_status. It never names those siblings, so differentiation is implied rather than stated.

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 type descriptions effectively explain which subscription to pick for odds-movement monitoring vs new-market discovery, which is real usage guidance. However, it gives no explicit when-to-use vs alert_status/alert_cancel, no prerequisites, and no guidance on how many alerts are reasonable or when a subscription should be cancelled.

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

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

With no annotations, the description carries the full burden; 'public' and 'Free' do usefully disclose that no auth or payment is required and that the data is not private. However it says nothing about behavior for an unknown handle, empty seasons, pagination of forecasts, or any error/limit conditions.

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?

One compact, front-loaded sentence with zero filler; the content list comes before the 'Free' qualifier. It reads as a fragment rather than a sentence, but nothing is wasted.

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

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

For a single-parameter read tool with no output schema and no annotations, the description covers what the record contains and its free/public nature, which is close to sufficient. Missing handle-format guidance and unknown-handle behavior keep it at minimum viable rather than complete.

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

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

Schema description coverage is 0% for the single required 'handle' parameter, so the description must compensate and largely does not — it implies the handle identifies an agent but never states format constraints (3-32 characters, case sensitivity, whether it is a username or opaque ID). This is a real gap for the only input.

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

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

Names the resource ('an arena agent's public record') and enumerates its contents: seasons, Brier scores and scored forecasts. The possessive 'an ... agent's' plus 'public' distinguishes it from arena_my_record/creator_record without naming them explicitly, so the resource is clear but the sibling contrast 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?

There is no when-to-use guidance and no named alternative such as arena_my_record for the caller's own data or arena_leaderboard for aggregate rankings. The agent must infer from context that this is the lookup-by-handle path.

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

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

With no annotations, the description must carry the full behavioral burden. It does disclose meaningful traits: the call is free, it requires an agent_key credential, it is an upsert rather than a pure create, and the target market must be open. It does not say what happens on validation failure, whether a forecast can be revised after market close, or whether repeated calls are rate limited.

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

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

Three short sentences, front-loaded with the action and the market scope, followed by the two mutually exclusive payload shapes. Every clause carries information an agent needs and nothing is repeated from the schema.

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

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

For a mutation tool with no annotations, no output schema, and a nested object parameter, the definition covers the essential calling semantics: credential, target, and the conditional shape of the two scoring parameters. What remains unstated is the success/failure response behavior and whether overwriting a prior forecast has side effects, which keeps it from a 5.

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

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

Schema coverage is 0%, so the description has to compensate, and it does for the two ambiguous parameters: probability is defined as chance of Yes on a 0-100 scale for yes_no markets, and probabilities is defined as an option_id-to-score map that must total 100 for multiple-choice markets. agent_key is framed as the credential ('free with your agent_key') and market_id is only named, though its UUID format is already in the schema.

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

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

States a specific verb pair ('send or update') and resource ('your arena forecast on an open Vatic market'), and implicitly separates forecast submission from sibling tools like ask_the_crowd or market_summary. It does not name a sibling alternative explicitly, so it stops just 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?

'On an open Vatic market' and 'send or update' imply the conditions (market must still be open, an existing forecast gets overwritten), which is useful implied guidance. However, there is no explicit statement of when to use this versus asking the crowd or reading a market, and no stated exclusion for closed or resolved markets.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one useful trait — that access is free — and that results are restricted to resolved markets, but says nothing about ordering, result limits, pagination, or whether seasons are archived or current.

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 short sentences, front-loaded with the substantive framing before the cost note. Minimal waste, though 'Vatic's' and the trailing 'Free.' are marketing-flavored fragments rather than operational 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-annotation, no-output-schema, single-parameter tool, the description conveys what the payload conceptually contains (agent rankings vs. human crowd by Brier score). It falls short on the season parameter and on any hint of result shape or size.

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 'season' parameter, so the description must compensate and does not — it never mentions seasons, their numbering, or what happens when the parameter is omitted. The agent cannot tell whether omitting it returns the current season or all-time standings.

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

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

The description names the resource (an agent forecasting leaderboard) and the ranking metric (Brier score on resolved markets), plus the comparative framing against the human crowd. It is clearly a read/report tool distinct from siblings like arena_agent or arena_forecast, though the verb is implicit rather than stated.

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 and no named alternative (e.g., arena_agent for per-agent detail) to steer selection. 'Free' hints that viewing the leaderboard costs nothing, but the agent must infer the use case entirely from the noun phrase.

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

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

No annotations are supplied, so the description carries the full burden. It discloses one behavioral trait — that the call is free when an agent_key is provided — which is useful pricing/auth context, but it never states that the operation is a read, whether it requires prior registration, or what the response contains. For an unannotated tool this leaves most behavioral questions unanswered.

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 short, front-loaded sentences with no filler or redundancy. The content is thin, but nothing is wasted and the key fact (record plus open forecasts) leads.

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 annotations and no output schema, the description is the only place an agent can learn what this returns, and it offers just 'record' plus 'open forecasts' without shape, ordering, or failure behavior. For a one-parameter tool the bar is low, but the definition still leaves the return payload and preconditions essentially undefined.

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 agent_key parameter, so the schema gives only a bare string type. The description adds meaning by tying agent_key to free access and to 'your' record, implying it is the caller's identity credential. That is genuine added value, but it stops short of saying what happens with an invalid or missing key.

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 the resource as 'your arena record, including open forecasts', which hints at a read of the caller's own profile plus pending forecasts. However, the verb is implicit and 'arena record' is never defined, so the agent cannot tell what fields or entity types come back. It does loosely differentiate from sibling creator_record via the possessive 'your', but only by implication.

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 when-to-use guidance at all — nothing says whether to call this before forecasting, after resolution, or instead of arena_agent or arena_leaderboard. The only contextual hint is 'Free with your agent_key', which is about cost, not about choosing this tool over a sibling.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses that the agent_key is shown only once, that ranking requires 10 resolved forecasts, that only rankings (no prizes) are at stake, and that entry costs $0.67 via x402/USDC. These are exactly the behavioral facts an agent needs before committing a paid, one-way action.

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

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

Four short sentences, front-loaded with the core action and scope, then the branching usage, then cost and reward terms. No filler; every clause conveys a fact the caller needs.

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

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

For a four-parameter, annotation-free, no-output-schema tool, the description covers the lifecycle (entry, secret key, free forecasts, ranking threshold), payment, and renewal path. The main remaining hole is the purpose of the homepage/description fields and any behavior on duplicate names.

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 25%, so the description must compensate; it explains the meaning of 'name' (for new agents) and 'agent_key' (for renewals), covering two of four parameters. The 'homepage' and 'description' parameters get no explanation in either the schema or the description, 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?

The description states a specific verb and resource ('Enter Vatic's agent forecasting arena for one 30-day season') and clarifies the two entry paths (new vs. returning agent), which an agent can distinguish from the forecasting siblings like arena_forecast. It stops short of naming a sibling tool explicitly, so it lands just below the top mark.

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 clearly routes the caller: new agents supply a name, returning agents supply an agent_key, and it notes forecasts become free after entry. There is no explicit when-not or named alternative (e.g., pointing to arena_forecast for submissions), but the context for use is unambiguous.

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

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

With no annotations, the description carries the full burden and does so well: it discloses an automatic safety/clarity check, that a rejection is not charged, the $0.30 x402/USDC cost, and that the return includes a secret resolve_token. These are non-obvious operational facts (cost, failure handling, credential-like output) that an agent could not infer from structured fields.

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

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

It is front-loaded with the core action and packs cost, safety check, return values, and next steps into a tight passage with no filler. The nested parentheticals and the trailing cost sentence make it slightly dense to parse, but every clause carries information.

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

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

For a mutation tool with no output schema, the description supplies the missing return contract (market id plus resolve_token) and the pricing/failure semantics, which is exactly what an agent needs to call it correctly. Nothing material about the call is left unstated.

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

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

Schema description coverage is 83%, so the schema already documents question length, closes_at constraints, and options requirements. The description only restates the yes_no/multiple_choice distinction already captured by the type enum, adding essentially nothing about the six parameters. 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 names a specific verb and resource — publish a Yes/No or multiple-choice prediction market to Vatic's human crowd — and explicitly distinguishes this from the read/resolve siblings by naming read_my_question and resolve_my_question. An agent can tell exactly what this tool creates without opening the schema.

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

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

It gives clear follow-up routing: use read_my_question for the live crowd probability and resolve_my_question once the outcome is known, which covers the full lifecycle. It does not state when to prefer the sibling ask_the_crowd_priority or any precondition for choosing this over it, so it falls short of full 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 no annotations, the description carries the burden and does well: it discloses the paid x402/USDC $1.00 cost, the 24-hour lobby pinning side effect, and that a slot-exhausted request is refused without charge rather than partially executed. It does not cover what happens after submission (resolution obligations, refunds, whether the pin can be extended).

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

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

Three short sentences, front-loaded with the differentiator, then the refusal rule, then the price. Dense and waste-free, with only minor cost from deferring the core action to a sibling reference.

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 paid creation tool with no output schema, the description covers cost, rejection, and visibility but never indicates what a successful call returns (e.g. a market id or confirmation) or what the agent can do next with it. The "same as ask_the_crowd" delegation covers some of this only if the agent already knows that sibling.

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 83% with per-field descriptions for options, question, closes_at, description, and resolution_source, so the schema does the heavy lifting. The description adds no meaning about any parameter, which is acceptable at this coverage level but leaves it at the 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 definition anchors on the named sibling ("Same as ask_the_crowd") and then states the concrete differentiator: the market is pinned in the players' lobby for 24 hours. It does not itself give a verb+resource (e.g. "create a paid, pinned market"), so an agent must resolve the sibling to know what is being asked, but the priority variant is clearly distinguished.

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 rationale for choosing this over the free sibling is implied by "so more people answer sooner," and the failure mode (refused when all priority slots are taken) is stated without saying when to fall back to ask_the_crowd. There is no explicit "use this when you need responses fast" guidance or budget/threshold advice for the $1.00 cost.

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

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

With no annotations, the description carries the full burden; it does disclose that the data is public and costs nothing, and it lists what the record contains. It does not state read-only semantics explicitly, error behavior for unknown usernames, or any response format, leaving meaningful gaps.

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

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

A single sentence with the resource and its contents front-loaded, followed by a one-word cost note. Nothing is padded and nothing repeats the name or title.

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

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

For a simple read-only lookup with one parameter and no output schema, the description adequately conveys what comes back. It falls short on the only input parameter and on failure modes, which matter given zero annotation and zero schema-description coverage.

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% and there is one required parameter, yet the description never mentions 'username' — no guidance on format, case sensitivity, exact-match, or where to obtain a valid creator handle. The constrained length (2-40 chars) is only visible in the schema.

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

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

The description names a specific resource — a Vatic creator's public record — and enumerates its contents: markets created and resolved, plus crowd-accuracy statistics. It implicitly contrasts with the sibling arena_my_record by emphasizing 'a creator's public record' rather than the caller's own, though the retrieval verb itself is only implied.

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?

No explicit when-to-use guidance and no named alternatives; the agent must infer that this is for looking up another creator's track record. 'Free' hints at cost but there is no mention of prerequisites, rate limits, or what to do when the username is unknown.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose the metric contents and that the call is free, which is useful beyond structured fields, but it omits whether results are over all time or a window, whether sample sizes are returned, and what happens with no category given (aggregate across all categories vs. error).

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

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

One compact sentence with the subject (crowd accuracy) and the three returned metrics front-loaded, followed by the segmentation and the cost note. No filler, nothing that fails to earn its 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 one-optional-param, no-output-schema read tool, the description covers what is measured and how it is grouped, which is most of what an agent needs. The remaining gap is the default behavior with no category supplied and the time horizon of the statistics.

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 enum parameter is fully enumerated in the schema. The phrase 'by category' still adds meaning: it clarifies that category segments the returned metrics rather than filtering rows, which the bare enum does not convey. Small but genuine value beyond the schema.

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

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

States a specific verb-free but concrete resource: the crowd's accuracy expressed as calibration bands, Brier score and favourite-win rate, segmented by category. An agent can distinguish this stats-reporting tool from siblings like arena_leaderboard or market_summary. It stops short of naming a sibling or explicitly saying it is a read-only aggregate report.

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 should reach for this when it needs to judge how reliable Vatic's crowd forecasts are. There is no explicit when-to-use, when-not, or comparison to alternatives such as arena_leaderboard (who is accurate) versus this (how accurate the crowd is). The trailing 'Free' hints at cost considerations but is not framed as 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?

No annotations are supplied, so the description carries the full burden. It does add real value by disclosing the return shape, the fact that probability is rounded, that outcome is conditional on resolution, and that the call is free (implying cost tiers exist elsewhere), but it is silent on permissions, error behavior for unknown ids, and whether data is live or cached.

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?

One front-loaded sentence with no filler; every phrase (field list, 'rounded', 'when resolved', 'Free') carries information. Slightly clipped to the point of terseness, but nothing is wasted.

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

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

For a single-parameter lookup with no output schema, the description usefully previews returned fields, which reduces the need for a return-value section. It remains incomplete on the one thing that actually gates correct invocation: what identifier to supply and what happens with an invalid or unresolved market.

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 parameter, so the description must compensate and it does not — the id parameter is never mentioned. It is unclear whether the id is a market UUID, a question id, or a slug, which matters given siblings like read_my_question and market_summary.

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 — a summary of one Vatic market — and enumerates what the summary contains (question, status, rounded probability, players, outcome when resolved). That is concrete enough to distinguish it from feed-style siblings like live_markets or recent_resolutions, though it never explicitly contrasts itself with market_summary or live_market.

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 when-to-use guidance: nothing says when to pick this over market_summary, live_market, or market_history, all of which sound adjacent. The only usage signal is implicit — that it needs a single identifier — so an agent must guess from names alone.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses a per-call cost of $0.002 via x402/USDC (a real gating fact an agent must plan for) and explains that probabilities are shares of free Vpoints with no cash value. It does not cover failure behavior for an unknown or malformed id, nor rate 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?

Three tight sentences, with the capability front-loaded, followed by the cost and then the interpretation of the returned numbers. Nothing is redundant and each sentence adds information an agent needs.

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

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

There is no output schema, so the description should say more about the shape of the 'pools' and 'players' data it promises; naming them without describing their structure is thin. Error behavior for a nonexistent market id is also unaddressed, though for a one-parameter read tool the essentials are present.

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

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

The single 'id' parameter has 0% schema description coverage, so the description must compensate. 'of one Vatic market' clarifies that the id identifies a market, but it does not say the id is a UUID or where to obtain one, leaving the parameter only partially 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?

States a specific verb and resource: fetches 'exact live crowd probability, pools and players of one Vatic market.' The singular 'one Vatic market' implicitly contrasts with the list-style sibling live_markets, but no sibling is named explicitly, so differentiation rests on 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?

'Exact live' implies use for current state rather than history, which quietly points away from market_history, and the stated price is a real decision signal. However, there is no explicit when-to-use/when-not guidance and no named alternative such as get_market or live_markets.

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

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

With no annotations, the description usefully discloses two things the schema can't: the call costs $0.01 via x402/USDC, and results are limited to open markets (100 max). It omits return shape, whether probabilities are percentages or 0-1 floats, and what happens on payment failure — meaningful gaps for a paid tool.

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

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

Two compact sentences with the core payload front-loaded and cost follow-up in a clear parenthetical. 'Exact' is mildly promotional, but nothing is wasted.

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

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

There is no output schema and no annotations, so the description must carry behavioral load; it covers what is returned at a high level and the payment model. For a 3-parameter listing tool with an undocumented sort parameter, it stops short of fully arming an agent 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 only 33%, so the description should carry more weight than it does. It restates the 'up to 100' cap already encoded as maximum:100 and says nothing about what sort=players/new/closing actually orders by, leaving the highest-impact parameter undocumented in both places.

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

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

Names a concrete resource ('open Vatic markets') and the payload ('live, exact crowd probabilities'), with a scope cap ('up to 100'). An agent can tell this is a bulk listing versus the singular live_market sibling, though the distinction is left implicit rather than stated.

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 by the word 'live' — nothing says when to pick this over live_market, trending_markets, market_history, or market_summary, nor whether it is a pre-step to get_market. No exclusions or prerequisites are given beyond the paid-call note.

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

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

With no annotations, the description carries the full burden, and it does contribute real behavioral context the schema cannot: a per-call cost of $0.01 via x402/USDC and the sampling cadence. It omits how the x402 payment is actually satisfied, whether repeated calls bill again, rate limits, and pagination or result-size behavior for a potentially long history.

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 tight sentence with the resource and scope front-loaded and the cost detail appended. Nothing is redundant or 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?

Given one required parameter, no output schema and no annotations, the definition supplies the two things an agent most needs before calling: what it returns (full timestamped probability history, one point per call) and that it is paid ($0.01, x402/USDC). Return-value explanation is unnecessary since granularity is stated.

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

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

Schema coverage is 0% – the lone 'id' parameter is documented only as a UUID pattern with no description. The phrase 'one Vatic market' does clarify that id is a market identifier rather than a user or question id, which is genuine added meaning, but nothing is said about invalid-id handling or whether the full history is returned unbounded.

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: 'full timestamped probability history of one Vatic market', with the sampling granularity '(a point after every call)'. This implicitly distinguishes it from snapshot-style siblings like get_market, live_market and market_summary, though it never names them.

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: 'history' versus a current snapshot suggests when to pick it, and the per-call point granularity hints at time-series use. There is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the routing decision.

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

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

With no annotations present, the description carries the full burden and does disclose a critical operational fact: it costs $0.02 via x402/USDC, meaning the caller must be prepared for a paid request. It also scopes the narrative ('how the odds moved, not why'), which prevents the agent from expecting causal analysis. It does not cover failure modes for invalid ids or latency.

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

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

A single dense sentence that front-loads the deliverable and ends with the cost, so the most decision-relevant facts come first. It is packed but every clause maps to a distinct output element or constraint; no filler.

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

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

There is no output schema, yet the description enumerates the return contents closely enough that an agent knows what it will get back. Combined with the disclosed price and payment rail, this is nearly complete for a one-parameter tool; only error behavior and how to source a valid market id 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?

Schema coverage is 0%, so the description must compensate; it partially does by making clear the single parameter selects exactly one market ('one Vatic market'), ruling out batch or multi-market use. It adds nothing about the UUID format, where to obtain a valid id, or what happens with an unknown id, so the compensation is only partial.

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 ('AI summary of one Vatic market') and enumerates exactly what the summary contains: crowd positioning, 24h and 7-day change, biggest moves, and a short written narrative. That distinguishes it in substance from the raw-data siblings like get_market or market_history, though it never names an alternative explicitly.

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 phrase 'AI summary' plus the $0.02 price tag signals that this is the interpretive, paid option versus raw market data. There is no explicit 'use this when…' or 'use get_market instead when you only need raw numbers,' so the agent must infer the tradeoff itself.

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

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

No annotations are supplied, so the description carries the burden. It does add real behavioral context – the read is live and 'free with your resolve_token' – which tells the agent about cost and credential requirements, but it omits whether the call is read-only/non-mutating, how fresh the probability is, and any rate limits or failure modes.

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 short sentences, front-loaded with the purpose and followed by the cost/credential note. Nothing is padded or repeated.

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 minimal two-parameter read tool with no annotations and no output schema, the definition covers what it fetches and that it is free, but it leaves the market identifier source, the shape of the returned probability, and the error behavior unstated.

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

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

Schema coverage is 0%, so the description must compensate. It clarifies that the 'token' parameter is the resolve_token, which is genuinely useful, but the required 'id' parameter is never explained – the agent must guess it is the market id returned by ask_the_crowd.

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

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

The description names a specific resource and scope: the live crowd probability of a market the caller created via ask_the_crowd. That scope word 'my/created with ask_the_crowd' signals it differs from generic market readers like get_market or live_market, though it never names an alternative explicitly.

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 by 'a market you created' – use it for your own markets, after asking the crowd. There is no explicit when-not guidance, no mention of what to do for markets you did not create, and no routing to siblings such as get_market or resolve_my_question.

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

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

With no annotations, the description carries the full burden and does disclose the 7-day window, the returned fields, and that access is free. However, it omits ordering, pagination, rate limits, authentication needs, and whether results are cached or real-time, leaving meaningful behavioral gaps.

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

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

The description is a single front-loaded sentence with no wasted words. It states the time window and the returned content immediately, and 'Free' is a concise useful signal.

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

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

For a simple read-only list tool with one optional enum parameter and no output schema, the description gives enough to understand what is returned and the time window. It does not cover ordering or pagination, but those are secondary for this low-complexity endpoint.

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% for the single optional category enum, so the schema already documents the parameter fully. The description adds no meaning about the category filter beyond what the schema provides, which is the baseline 3.

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

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

The description clearly states a specific resource and scope: Vatic markets resolved in the last 7 days, with outcome, closing crowd odds, and favourite result. It does not differentiate itself from the sibling resolutions_feed, 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 guidance, no exclusions, and no named alternative such as resolutions_feed. The word 'Free' hints at cost but does not tell an agent when this tool is preferable to another.

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?

Without annotations, the description carries the full burden. It discloses important behavioral traits: cost ($0.01 via x402/USDC) and data quality (verified outcomes with sources and exact probabilities). However, it omits potential details like rate limits, pagination behavior, or whether authentication beyond payment is required.

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 two sentences, front-loaded with the core purpose and followed by cost information. Every sentence earns its place with no unnecessary wording.

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

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

For a simple feed with no output schema, the description should explain the return values more concretely. It conveys the content (verified outcomes, sources, final probabilities) but not the structure (e.g., array of objects, fields) or pagination details. This gap leaves the agent partially informed.

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 67% (since and category have descriptions; limit does not). The description adds a small amount of meaning by mentioning 'any date range,' which loosely relates to the 'since' parameter, but it does not explain the 'limit' or 'category' parameters beyond what the schema already provides.

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

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

The description states a specific resource: 'Verified outcomes of resolved Vatic markets with sources and exact final probabilities, any date range.' This clearly identifies the tool's output and scope. It doesn't explicitly name a sibling alternative, but 'any date range' implies a broader scope than a 'recent' feed, providing some differentiation.

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 guidance on when to use this tool versus alternatives (e.g., recent_resolutions), no exclusions, and no prerequisites mentioned. The description merely states what the tool returns and its cost.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that payouts happen immediately, players can report a wrong result, and the action is free with a resolve_token, but it does not state whether resolution is irreversible, what permissions are required beyond token ownership, or what status the market enters afterward.

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 compact and front-loaded, with three sentences that each carry relevant information. The final sentence about the resolve_token is slightly abrupt but still earns its place by clarifying cost/access.

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

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

For a mutation tool with no annotations, five parameters, low schema coverage, and no output schema, the description is only partially complete. It covers the core purpose and some consequences, but it omits return behavior, error conditions, and full parameter semantics, leaving gaps an agent would need to infer.

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

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

Schema description coverage is low at 20%, so the description needs to compensate. It indirectly explains id as the market you created, token as your resolve_token, and source as the evidence for the outcome, but it does not explain the outcome parameter's yes/no enum or the option_id parameter for multiple-choice markets.

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 uses a specific verb and resource: it resolves a market created with ask_the_crowd and requires a source for the outcome. It distinguishes itself from ask_the_crowd by referring to the creation relationship, though it does not explicitly contrast with read_my_question or other resolution 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?

It implies the use case: resolve a market you created, using a resolve_token. There is no explicit when-not guidance, no mention of alternatives such as read_my_question, and no handling of edge cases like already-resolved markets.

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

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

With no annotations, the description carries the burden and does add real behavioral context: data can be up to 15 minutes stale, probabilities are rounded, the service is free, and prices derive from play-money Vpoints with no cash value. It still omits pagination/rate-limit behavior and roughly what fields or how many items come back.

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

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

Three short sentences, front-loaded with what the tool returns, followed by cost and an interpretation note for the probability values. No filler; each sentence contributes distinct information.

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

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

For a two-parameter listing tool with no output schema and no annotations, the description covers freshness and price semantics but leaves the default/limit behavior and the return shape unexplained. An agent can call it, but cannot predict result size or how 'most played' is measured.

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%: the category enum is documented in the schema, but 'limit' (1-50) has no description anywhere and is never mentioned in the description. The description adds no parameter meaning at all, so it 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?

States a specific verb-like action (retrieve most played open prediction markets) on a named resource (Vatic markets), with ranking ('most played') and status ('open') qualifiers. An agent can tell this is a discovery/listing tool, though it never names how it differs from siblings like live_markets or market_summary.

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: 'most played open' markets suggests browsing popular open markets rather than looking up a single market (get_market/live_market) or history. There is no explicit when-to-use statement, no exclusions, and no named alternative to route to when a different market view is needed.

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