Cito API

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

Beyond the readOnly/openWorld/destructive annotations, the description adds valuable behavioral context: parallel-safety, upstream cost range, best-effort probing behavior, and which error situations warrant calling it. This gives the agent a clear model of the tool's side effects and operational 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?

The description is tightly organized with front-loaded output information, a compact when-to-use list, and a short example. Every section earns its place, and there is no filler or redundant repetition of schema fields.

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?

Despite having an output schema, the description still supplies operational context such as upstream cost, parallel-safety, and error recovery triggers. For a simple single-parameter health-check tool, this is complete enough for an agent to select and invoke it correctly.

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

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

The schema already documents includeGameProbes at 100% coverage, so the baseline is 3. The description adds a concrete usage example and links the parameter to the 'best-effort included games' behavior, making the optional flag's purpose clearer without repeating 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 states exactly what the tool reports: API reachability, API key validity, plan tier, rate-limit headers, and best-effort included games. It clearly differentiates from siblings by naming live_matches as the alternative for live scores.

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

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

Provides explicit when-to-use scenarios, including once per session, after specific errors, and for entitlement checks. It also gives a 'Prefer over' instruction and a 'Do not use when' rule, which is exactly the kind of routing guidance an agent needs.

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 mark it read-only/open-world/non-destructive; the description adds path validation behavior, PATH_NOT_ALLOWED errors, parallel-safety guidance, and upstream cost of 1. This goes well beyond what the annotations provide.

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?

Although longer than average, the description is tightly organized with labeled sections and no filler. The opening one-liner, usage bullets, path constraints, safety notes, and example each add distinct value in a scannable order.

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?

The output schema exists, and annotations cover safety/open-world behavior, so the description need not explain return values. It covers when to invoke, when not to, path constraints, error behavior, rate-limit caution, and a full call example.

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 all five parameters are already documented with descriptions and examples. The description adds a concrete usage example and emphasizes the path allowlist, but most parameter-level meaning 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?

Opens with a specific framing: 'Power escape hatch: allowlisted Cito REST call with unshaped raw JSON in data.raw.' It names the exact action, target resource, and output shape, and positions itself against curated siblings as the long-tail fallback.

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 lists three use cases (long-tail paths, debugging payloads, user knows an OpenAPI path) and gives a direct exclusion: 'Do not use when: a curated tool covers the outcome.' It also names curated job categories to prefer and adds rate-limit caution.

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 only declare readOnly, openWorld, and destructive-safe, so the description carries the behavioral burden. It adds card ordering, bout/corner field details, the CORS/proxiedImageUrl caveat, parallel-safety, upstream cost, the extra includeStandings call, and tennis draw behavior—far beyond the structured 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 long but every section earns its place: definition, use cases, return behavior, CORS warning, alternative routing, exclusions, tennis path, and a concrete example. It is front-loaded with the core identity and organized so an agent can scan it efficiently.

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 composite, multi-game tool with six parameters and many siblings, the description is complete: it covers selection criteria, alternative tools, exclusions, field semantics, cost, safety, parallel execution, and special tennis behavior. Since an output schema exists, return-value documentation is not required here.

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%, but the description adds meaningful behavior beyond it: q resolves within the tool and should defer to resolve_entity for disambiguation; includeMatches includes the tennis draw bracket; includeStandings joins divisional rank onto corners and costs an extra upstream call. These are the kind of side effects an agent cannot infer from the schema alone.

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 'COMPOSITE event / fight-night card: identity, bout or match list, optional standings snippet,' which clearly names the resource and scope. It also distinguishes itself from siblings by pointing to match_preview for one bout, match_summary for recaps, live_matches for live-only, and standings for pure tables.

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 'When to use' section lists concrete scenarios, including UFC fight nights, CS2 event hubs, and tournament overviews. 'Prefer over' and 'Do not use when' explicitly route the agent to alternatives and state exclusion conditions, and the tennis guidance adds platform-specific handling.

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 indicate read-only and non-destructive behavior; the description adds meaningful context: server-side filtering instead of a native endpoint, weaker Dota filters with meta.warnings, parallel-safety, and upstream cost. These go beyond the structured annotations and inform safe invocation.

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 front-loaded purpose, clear usage sections, a caveat, and an example. Every sentence adds value, and the length is justified given the number of parameters, siblings, and the need to disambiguate from related tools.

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 rich input schema, annotations, output schema, and explicit routing to sibling tools, the description covers all essential context an agent needs. It includes limitations, parallel-safety, cost, and a concrete invocation example, so no critical operational gap remains.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description's example clarifies expected slug-style values but adds no new semantic meaning beyond what the schema provides, so the baseline of 3 is 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 description clearly states the resource: a composed head-to-head record between two teams, UFC fighters, or tennis players. It also differentiates itself by noting that no first-class REST H2H exists and by explicitly routing single-side questions to team_profile or player_profile.

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 explicit when-to-use scenarios, a 'prefer over' instruction, and a direct 'do not use when' rule with named sibling alternatives. This leaves little ambiguity about when an agent should select this tool.

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

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

Annotations already cover readOnlyHint, openWorldHint, and destructiveHint. The description adds useful behavioral context: the result is a curated catalog (not a raw API dump), it is parallel-safe, and it has zero upstream cost. This goes beyond the structured annotations without contradicting them.

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

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

The description is scannable and front-loads the purpose. Every section earns its place: use cases, exclusions, parallel-safety, upstream cost, and a concrete example. No fluff or repetition.

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?

The description fully covers when to use, when not to use, safety behavior, upstream cost, and gives an example call. With an output schema present, the agent has everything it needs to decide whether and how to invoke this tool.

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

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

The input schema has 100% coverage with descriptions for each parameter, so the baseline is 3. The description adds an example payload and a shorthand list of job filters, which clarifies how to combine game/job/includeExamples in practice.

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 first sentence defines the resource: the curated catalog of cito-mcp tools, games, jobs, and builder recipes. It is clearly distinct from data-lookup siblings like live_matches or match_details, and it explicitly contrasts itself with call_api for discovery use.

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

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

Provides explicit 'When to use', 'Prefer over', and 'Do not use when' sections. This gives an agent concrete routing rules, including the exclusion case where direct tool calls should win.

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 carry readOnlyHint=true and destructiveHint=false; the description adds a meaningful caveat about the /lol spec omission and that filtering by game=lol returns a caveat rather than an empty list. It also states 'Parallel-safe: yes. Upstream cost: 1.' No contradiction with 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?

Front-loaded with a one-line purpose, then compact sections for when-to-use, caveats, and example. Every sentence carries useful signal and no padding.

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

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

With an output schema present and annotations covering safety, the description supplies usage boundaries, a known edge case, operational semantics (parallel-safe, upstream cost), and an example. Nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds a concrete example combining game and q, and warns about game=lol's special behavior, giving the agent more than the raw schema 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?

States a specific verb and resource: 'Index of raw REST routes from the live OpenAPI spec: method, path, summary, tag.' It also differentiates from list_capabilities by calling it 'the escape hatch' and clarifying it is 'not a replacement for list_capabilities', so an agent can distinguish it from 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?

Provides an explicit 'When to use' list covering concrete needs (long-tail path for call_api, checking endpoint existence, mapping raw data) and a 'Do not use when' clause directing to list_capabilities when a curated tool covers the outcome. The alternative is named directly.

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

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

Beyond the readOnly/openWorld/destructive annotations, the description discloses important behavioral details: parallel-safety, upstream cost range, CS2 live path, UFC empty-board handling including health fields and a warning never to fabricate match items from events[]. This is exactly the kind of operational nuance an agent needs.

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

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

The description is well-structured with clear sections: a one-line purpose, when-to-use, when-not-to-use, per-game edge cases, and performance notes. It is front-loaded with the core behavior and every section earns its place without unnecessary 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?

For a read-only live-matches tool with 3 optional parameters and rich annotations, the description is complete: it covers alternatives, edge cases (UFC empty board), performance characteristics, and example usage. The presence of an output schema means return-value documentation is not required here, so nothing important is missing.

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

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

The input schema already covers all parameters fully (100% schema description coverage), so the baseline is 3. The description adds value with a concrete usage example ({ "game": "all", "limitPerGame": 10 }), clarifies the single-game filter concept, and reinforces batching behavior via limitPerGame, slightly exceeding the schema alone.

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

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

The description states the tool provides a live matches board across primary games or a filtered single game, with normalized labels, scores, and matchIds. It explicitly distinguishes itself from upcoming_schedule, match_summary, and per-game call_api probes, so an agent can clearly understand what this tool is for.

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 explicit when-to-use scenarios ('What's live right now?', ops/dashboard live strip), names a preferred alternative path (avoid sequential call_api probes), and provides do-not-use guidance with direct sibling alternatives (upcoming_schedule, match_summary). This leaves minimal ambiguity about tool selection.

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

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

Beyond the readOnly/openWorld annotations, the description discloses non-obvious behavior: section precedence ('If sections[] is non-empty it wins'), per-game requirements ('LoL liveState/advanced require gameId'), opt-in odds, parallel safety, and upstream cost range. These are exactly the behavioral details an agent needs to call it correctly and safely.

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 organized into scannable labeled blocks (When to use, Prefer, Do not use, Section selection, Parallel-safe), front-loading the core purpose and then diving into edge cases. No filler: every sentence conveys a distinct, decision-relevant fact, and the JSON example at the end is a useful concrete anchor.

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

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

For a tool with 7 parameters, an output schema, and sibling alternatives, the description covers the purpose, usage boundaries, parameter interplay, special cases, and cost behavior. The presence of an output schema means the return-format burden is lifted, and the description fills all selection and invocation gaps.

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%, yet the description still adds semantic value by explaining how the booleans interact with sections[], which sections are defaults, that odds are opt-in, and what gameId is needed for. The example input further clarifies parameter usage in context.

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 'Deep match package: optional timelines, advanced stats, live state/snapshots, full map/game tree, media inventory,' which names the exact resource and scope of the tool. It also explicitly contrasts with match_summary, giving the agent a clear way to distinguish this tool from a key sibling before inspecting schemas.

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

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

The 'When to use' bullets list concrete analyst and live-window scenarios, and the description explicitly states when to prefer match_summary and when to avoid this tool ('first-pass live board (use live_matches + match_summary)'). This is textbook alternative selection 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not required to restate safety. It adds useful behavioral context beyond annotations: it is a composite tool, parallel-safe, with an upstream cost of 4–8, and it returns pre-match briefing content. No contradiction with annotations exists.

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 a dense summary line, clear usage bullets, explicit exclusions, and a compact example. Every section adds decision-relevant information without repetition or 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?

For an 8-parameter tool with a high-coverage schema, an output schema, and strong annotations, the description covers the essential context: what it returns, when to use it, when not to use it, how it compares to siblings, and a realistic invocation example. Nothing critical for an agent to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a concrete example invocation and clarifies the composite relationship between sides, H2H, and recent form, but it does not substantially elaborate on individual parameters beyond what the schema already documents.

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

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

The description opens with 'COMPOSITE pre-match briefing' and enumerates the content: sides, roster/form snippets, H2H stub, event context. It clearly differentiates from siblings by explicitly labeling this as pre-match and directing completed matches to match_summary and live matches to match_details.

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 explicit 'When to use' bullets, a 'Prefer over' note, a 'Prefer match_summary when...' instruction, and a 'Do not use when' exclusion. This gives an agent unambiguous decision criteria for selecting this tool over alternatives.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds non-obvious behavior: 'Parallel-safe: yes', 'Upstream cost: 2–5', and data availability caveats like 'when available'. This goes beyond the annotations, though it does not detail error cases or rate limiting.

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 a one-line summary, bulleted usage guidance, routing notes, negative cases, and a compact example. Every section earns its place, and the most important information is 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 the rich input schema, existing output schema, read-only annotations, and clear sibling differentiation, the description covers what an agent needs to call the tool correctly. It also includes parallel-safety and upstream cost context, making it complete for this level of complexity.

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 schema fully documents all five parameters. The description adds a concrete usage example and links concepts like 'player performances' and 'VOD/demo links' to the relevant parameters, but it does not add substantial meaning beyond the schema's own parameter descriptions.

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 opening phrase, 'COMPOSITE match card', and enumerates the delivered content: scoreline, key context, player performances, and VOD/demo links. It explicitly distinguishes this tool from match_details and match_preview, so an agent can easily tell what this tool is for.

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 a dedicated 'When to use' section, explicit routing guidance ('Prefer over match_details'), and clear negative cases such as 'no matchId yet' and 'pure pre-match → match_preview'. This leaves no ambiguity about when to call this tool versus its 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 read-only, open-world, and non-destructive behavior. The description adds useful context beyond that: data may be unavailable ('when available'), parallel safety is guaranteed, and upstream cost is 2–5. This 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: core purpose first, then compact labeled sections for usage, exclusions, operational notes, and an example. No sentence is wasted, and the example is concise while illustrating key parameters.

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 output schema exists, return-value details are not needed. The description covers purpose, usage, alternatives, exclusions, parallel safety, cost, and a representative call, making it complete for this 8-parameter read-only tool.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds a concrete example JSON but doesn't materially enrich parameter meaning beyond what the schema provides, so the baseline of 3 is 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 description clearly identifies the resource as a player or UFC fighter profile and enumerates the content: identity, current team, recent matches, and form/trends/radar. It also distinguishes itself from related sibling tools like team_profile and resolve_entity, so an agent can tell them apart.

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 explicit when-to-use examples, a 'Prefer over' note for call_api, and a 'Do not use when' section naming team_profile and resolve_entity. This gives an agent complete routing guidance with no ambiguity.

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 convey readOnlyHint, openWorldHint, and destructiveHint, and the description adds substantial behavioral context: empty/ambiguous results still return ok:true with best=null or needsDisambiguation=true, no hard AMBIGUOUS_ENTITY error, parallel-safety, and upstream cost. This goes well beyond what annotations alone provide.

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 a front-loaded summary, clear use-case sections, an example, and no filler. Every sentence contributes either scoping, alternative selection, edge-case behavior, or operational cost 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 fuzzy-resolution tool with output schema available, the description covers the full decision context: when to use, when not to use, how it differs from the closest sibling, behavior on ambiguous results, cost, parallelism, and an example. Nothing an agent needs to invoke it correctly is missing.

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

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

Input schema coverage is 100%, so the schema already fully documents q, game, type, and limit with enums, defaults, and examples. The description adds practical selection guidance ('small ranked set to chain', 'pick from candidates or refine q/game/type') and a concrete example call, which elevates it above the baseline without needing to compensate for schema gaps.

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 immediately defines the tool's specific purpose: 'Natural-language / fuzzy query → best typed entity ID(s) + game', listing entity types. It explicitly distinguishes itself from the sibling search_entities by describing when each should be used, so an agent can reliably tell them apart.

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 explicit when-to-use scenarios ('User named an entity without an ID', 'Need a canonical id/slug before profile or match tools'), a direct contrast with search_entities ('Prefer over search_entities when you want one best match... Prefer search_entities when browsing many results'), and a clear exclusion ('Do not use when you already have a stable id/slug').

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 (readOnlyHint=true, openWorldHint=true, destructiveHint=false), the description discloses UFC-specific ranking behavior, client-side re-ranking, the guarantee that 'Jon Jones' returns jon-jones first, parallel-safety, and upstream cost. This gives the agent behavioral expectations well beyond what annotations provide.

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 organized into clear sections — purpose, when to use, when not to use, special behavior, and an example. Despite its length, every section earns its place and no information is redundant or 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?

Given six parameters, multiple sibling tools, and an output schema that already documents return shape, the description covers all necessary context: use cases, exclusions, alternative selection, ranking behavior, parallel-safety, cost, and a representative call example. Nothing required for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the q parameter's ranking semantics for UFC, providing a concrete example object, and clarifying that type filters and pagination are core behaviors rather than just schema fields.

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

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

The description opens with a specific verb-resource pair: 'Browse/search teams, players, tournaments, events, fighters with type filter and pagination.' It then differentiates itself from resolve_entity, team_profile, and player_profile, so an agent can immediately tell what this tool is for and what it is not.

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 guidance is explicit and concrete: typeahead/pickers, list requests, entity exploration, and UFC fighter lookup. It also names the preferred alternative for the opposite case ('Prefer resolve_entity when chaining one name into a profile tool') and states a negative rule with the correct sibling tool to use instead.

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 and destructiveHint=false, but the description adds substantial behavioral context beyond that: 'Parallel-safe: yes. Upstream cost: 1–2,' the Dota limitation ('may NOT_IMPLEMENTED or weak worldRanking'), and the pagination caveat ('UFC world scope spans every division; page with it rather than raising limit'). These are exactly the kind of behavioral traits an agent needs and that structured annotations do not convey.

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

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

The description is information-dense with no filler: every section earns its place, from purpose and alternatives to per-game scope, parallel-safety, cost, and an example. It uses clear section headers and bullets, keeping the content scannable. Despite its length, it is appropriately sized for the tool's complexity.

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 multi-game standings tool with 10 parameters, the description is remarkably complete: it covers use cases, exclusions, per-game parameter requirements, known limitations, operational traits (parallel-safety, cost), pagination guidance, and a concrete example. Since an output schema exists, return-value documentation is unnecessary. Nothing an agent needs to call this tool correctly is missing.

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

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

Although the schema already achieves 100% description coverage, the description adds critical cross-parameter semantics that the schema cannot express: game-dependent required keys (lol: leagueId OR tournamentId; cs2: omit for world rankings; eventId for event standings; dota2: best-effort worldRanking only). It also adds usage nuance for cursor and limit in the UFC pagination note. This goes well beyond the baseline for high schema coverage and meaningfully improves parameter selection.

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 clear, specific statement: 'League/event standings or world/division rankings normalized to ranked rows.' It names the resource (standings/rankings), the output format (normalized rows), and immediately distinguishes from siblings via 'Prefer over: raw standings via call_api' and 'Do not use when: single team form → team_profile; live scores → live_matches.' An agent can confidently tell this apart from the listed alternatives.

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 guidance is explicit and structured: a 'When to use' bullet list covers table/playoff picture and per-game use cases, a 'Do not use when' section names exact alternatives (team_profile for single-team form, live_matches for live scores), and a per-game 'Required scope keys' section tells the agent exactly which parameters to provide for each game. This is comprehensive, actionable 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 read-only and open-world annotations, the description discloses parallel-safety, upstream cost of 2–4, the Dota partial-roster API gap, and the fact that form/trends/radar are only returned 'when available.' No contradiction with annotations exists.

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?

Every line earns its place: concise summary, direct usage conditions, clear exclusions, known caveat, cost hint, and a concrete example. The structure front-loads the core purpose and then layers decision-relevant guidance.

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 six-parameter tool, the description covers when to use, when not to use, parameter preferences, API limitations, cost, concurrency safety, and includes an example. Combined with the output schema and rich parameter descriptions, nothing critical is missing for an agent to invoke it correctly.

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

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

Although schema coverage is already 100%, the description adds valuable selection guidance: prefer slug for lol/cod, teamId for cs2, and note that at least one of teamId/slug is required. The example payload further clarifies how parameters combine.

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 resource and content list: 'Team/org card: identity, roster, recent matches, and form/trends/radar when available.' It also explicitly distinguishes itself from player_profile and call_api, so an agent can tell exactly what this tool covers relative to 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?

Provides explicit 'When to use' and 'Do not use when' sections, including routing to player_profile for UFC fighters and resolve_entity for unknown names. It also names call_api as an alternative to prefer this tool over, giving clear decision criteria.

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 mark the tool read-only and non-destructive, and the description adds substantial behavioral context beyond that: unsupported params are silently ignored with meta.warnings, per-game filter application varies, 'hours not applied upstream' for cs2, client-side filtering for dota2/ufc, parallel safety, and upstream cost. These are critical operational details not derivable from the schema or annotations.

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

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

The description is longer than average but every section earns its place: purpose, usage context, exclusions, per-game filter caveats, parallel safety, cost, and an example. The bulleted structure keeps it scannable and the critical filter caveat is front-loaded before the per-game 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?

For a multi-game tool with 9 parameters, varying filter support, and an output schema available, this description is complete. It covers what the tool returns conceptually, when to use it, when not to, per-game filter limitations, ignored-parameter behavior, and performance characteristics. Return-value details are appropriately left to the output schema.

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?

Although schema coverage is 100%, the description adds meaning the schema cannot convey: which parameters are actually honored per game, which are ignored, and which are applied client-side rather than upstream. The worked example '{"game": "lol", "hours": 72, "team": "t1", "limit": 20}' further clarifies intended usage.

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: 'Upcoming matches/events for one game, with game-specific filters.' It immediately differentiates from the sibling 'live_matches' by stating 'Prefer over: live_matches for not-yet-started fixtures,' so an agent can tell which tool matches the requested state.

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

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

Usage guidance is explicit: 'When to use' bullets cover calendar UI and team next-match queries, and 'Do not use when: only in-progress matches needed → live_matches' provides a direct exclusion and alternative. This is exactly the kind of when-versus-sibling guidance an agent needs.

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