disputes.online

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description's field enumeration (question, outcomes, stakes, deadlines) largely restates what the output schema would carry; only the settled-dispute behavior (returns winning outcome alongside crowd bets) is genuinely additive. No auth or rate-limit 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?

Two front-loaded sentences with the lookup key stated immediately and no filler. The middle field enumeration is somewhat list-heavy but each item is a distinct part of the dispute model.

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

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

An output schema exists, so return values need not be explained, and the description still covers input form, scope (single dispute), and a practical use case. Only the absence of guidance on what happens with an unknown or malformed id leaves a minor gap.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'the dispute's id (UUID) or the URL of its page'. The description repeats the same id-or-URL detail without adding format, validation, or resolution rules, 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?

States a specific verb and resource ('Get one dispute from disputes.online') and pins the retrieval key ('by its id or page URL'), which cleanly separates it from the sibling list/search tools that return collections.

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

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

Gives a concrete usage scenario ('use it to check a past prediction') and notes it also resolves already-settled disputes, which is clear context for selection. It never names the alternative tools or states a when-not condition, 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 readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered. The description adds useful behavioral context beyond that: the result is a flat tree structure, and the tool's role is to supply category_id values. It doesn't discuss ordering or size limits, but an output schema exists, so return detail is less critical.

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, zero waste, with the purpose front-loaded and the practical usage instruction second. Every clause earns 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?

With no parameters, an output schema present, and annotations covering the safety profile, the description supplies exactly what is missing: what the tool lists, its flat-tree shape, and the workflow reason to call it. Nothing an agent needs before invoking it is absent.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. Full schema coverage (100%) and no required inputs mean no parameter risk remains.

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 (List) and resource (categories) with scope ('disputes on disputes.online are filed under') and even the return shape ('flat tree'). An agent can distinguish this from search_disputes, search_disputes_by_tags, and get_dispute without opening any schema.

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

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

Explicitly tells the agent when to use it: to obtain the category_id for a topic before calling search_disputes, naming the downstream sibling. It lacks any when-not or alternative-selection guidance, but the usage context is clear and actionable.

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=true, idempotentHint=true and openWorldHint=false, so the safety and idempotency profile is covered. The description adds only the scoping fact that returned disputes are 'open to bets' — it says nothing about whether closed/resolved disputes are excluded wholesale, or how paging behaves across result sets.

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 clauses: what is returned, what can be filtered/sorted, and why to use it. The capability statement is front-loaded and every sentence carries information — no boilerplate, no repetition of the 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?

With an output schema present, the description needn't explain return values, and 100% parameter coverage handles the inputs; annotations carry the safety profile. What remains thin is paging/result-set behavior across limit/offset and whether non-open disputes are ever visible, but the definition is sufficient to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents lang, sort, limit, offset, country and category_id in detail, including defaults and id ranges. The description's 'filter by language, category and country; sort by pool size, number of bets or closing time' merely paraphrases the schema without adding formats, ordering caveats or defaults.

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 — listing disputes that are 'open to bets' — and names the returned payload ('each outcome's share of the stakes'), which is a precise, non-tautological purpose. It implies its distinction from search_disputes_by_tags by enumerating its own filter axes, but never names a sibling, so an agent must infer the routing.

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

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

Gives explicit positive context: 'find what people are currently predicting about a topic, or what the crowd thinks the odds are.' That tells an agent when this tool is the right call. It stops short of exclusions or naming search_disputes_by_tags as the alternative for tag-driven queries, so no 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 readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds a real behavioral trait not in the schema or annotations: that only *open* disputes are returned, which materially shapes results.

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 sentences, both earning their place: the first states scope, the second states when to reach for it over coarser filters. No repetition of schema details.

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

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

An output schema exists, so return values need not be described. The description covers scope, the open-status filter, and the selection context; only the explicit alternative tool name and paging context are absent, which is minor.

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 tags, lang, limit, and offset are all documented in the schema itself (including the any-of matching rule). The description adds nothing beyond 'by tag', 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?

States a specific verb (Find) and resource (open disputes by tag) with a named platform, and the second sentence positions it against the category/country-filtering sibling (search_disputes). An agent can tell this apart from search_disputes and list_categories without opening any schema.

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

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

The description gives a clear selection rule: use it for a specific subject (person, team, asset) when category and country are too coarse, which implicitly contrasts with the category/country-based sibling. It stops short of naming the alternative tool or stating when not to use this one.

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