turnale

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

With annotations only providing false flags, the description carries the burden of disclosing side effects. It does so effectively by stating that duplicate names are rejected and that an unlocked draw is regenerated automatically. These are important behavioral traits that go beyond the schema and annotations, giving the agent a clear picture of the tool's impact.

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 three sentences and front-loads the core purpose. Every sentence adds value: purpose, preparation guidance, and side effects. No filler or redundancy.

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 covers purpose, usage guidelines, alternatives, and key side effects. With an output schema present and parameter schemas for most fields, no critical context is missing. The tool's behavior is fully captured 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?

Schema description coverage is 67%, and the players array itself lacks a schema description. The description compensates by implying that the players parameter must contain structured entries, not raw text, and warns against inventing placeholder names, adding meaning beyond the input schema. Fields like level and gender are well-covered by schema, so the description complements rather than repeats.

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 'Add players to the roster in bulk', a specific verb and resource that clearly states the tool's function. The bulk aspect distinguishes it from siblings like update_player, replace_player, and signup mode, making the purpose unmistakable.

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 usage guidance: it instructs to parse pasted lists or spreadsheets yourself and send structured entries, and explicitly says to use signup mode when names aren't known yet, providing a clear alternative. This tells the agent exactly when and how to use the tool versus other workflows.

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?

Discloses that omitting format returns a menu and creates nothing; warns the organiser key cannot be recovered; forbids inventing placeholder names; explains signup_open/cap behavior; and derives rounds from a time budget. This goes well beyond annotations, which only flag readOnlyHint=false.

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 sentence adds operational guidance. It is front-loaded with the core action, then structures the guidance as direct imperative instructions. No fluff, though it could be organized with bullets for readability.

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

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

Covers edge cases like time-budget derivation, unlisted formats, signup flows, and the non-recoverable organiser key. Given 27 parameters and an output schema, this description provides enough context to use the tool correctly without external manuals.

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 81% schema coverage, the schema already documents most parameters. The description adds value by naming the four must-ask parameters and clarifying that format should be omitted when not clearly chosen, tying to the parameter's semantics. It also explains the rounds parameter via time-budget derivation.

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 'Create a new tournament', a clear verb-object pair that names the resource. It also distinguishes from siblings by noting players can be added later with add_players and by describing the format-menu fallback, which differentiates it from direct creation tools.

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

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

Explicitly instructs to keep setup short and lists which parameters to ask for (sport, players, court count, start time). Names alternatives: 'Players can be added later with add_players' and 'offer to note it with record_feedback' for unlisted formats. Also explains when to omit format instead of asking an open 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?

Beyond the destructiveHint annotation, the description discloses it's a soft-delete, recoverable for 7 days, and requires confirm: true. This gives critical behavioral context the annotation alone lacks.

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

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

Single, front-loaded sentence with all necessary information; no wasted words.

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 destructive action, the description covers the action, recovery window, and confirmation requirement. Output schema exists so return values need not be described; slight gap on what 'preview' entails but acceptable.

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 description explains the 'confirm' parameter ('true to apply') but does not describe 'tournament_key', relying on the parameter name. Since schema description coverage is 0%, the description partially compensates but could be more explicit.

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 action ('Soft-delete the whole tournament') with a specific verb and resource, and distinguishes from sibling tools like end_tournament or remove_player by indicating the scope ('whole tournament'). The recovery note also clarifies the nature of the delete.

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 usage guidance: 'Preview first; confirm: true to apply.' This tells the agent the prerequisite and required confirmation. However, it does not explicitly name alternative tools or exclusions, so not 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?

The description discloses important behaviors beyond the annotations: if matches are pending, the tournament ends early and standings freeze. It also reveals the preview/confirm mechanism. Annotations only state readOnlyHint=false and destructiveHint=false, but the description adds situational context about what happens to pending matches, which is valuable for the agent.

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, with the main action front-loaded. Every sentence provides necessary context: what happens on early end and the preview/confirm process. No wasted words.

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 moderate complexity, the 100% schema coverage, and the existence of an output schema, the description is complete. It explains the critical behavior (pending matches, freeze) and the confirmation flow, so the agent can select and invoke correctly without further information.

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, so the baseline is 3. The description goes beyond by explaining the preview/confirm flow, which directly maps to the 'confirm' parameter. It doesn't detail tournament_key or request_id, but the schema already handles those. The added semantic about preview/confirm elevates it to 4.

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 tool's purpose: 'Finish the tournament.' It specifies the verb and resource, and adds key behavioral detail about early ending and freezing standings, which distinguishes it from sibling tools like delete_tournament or update_settings.

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 clear usage context: preview first, then confirm to apply. It implies when to use (when you want to end the tournament) but does not explicitly mention alternatives or exclusion scenarios. Still, the two-phase preview/confirm guidance is a strong usage guideline.

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 destructiveHint annotation, the description discloses critical behaviors: it moves tournament state, closes self-signup, discards recorded results after first result, and requires an explicit discard acknowledgement. It also explains the preview/seed mechanism, adding rich 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 dense but efficient; every sentence adds valuable information. It is front-loaded with the core action and then expands into usage details. No wasted words, though it could be slightly restructured for easier scanning.

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

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

For a complex, destructive mutation tool, the description covers all essential flows: starting the tournament, previewing with seed, confirming, redrawing, handling existing results, and unsupported format feedback. The output schema exists and rounds_text is explicitly mentioned, making the tool's behavior fully understandable.

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 description adds meaning to key parameters (seed, confirm, discard_results) and explains the preview/confirm relationship. However, schema coverage is only 45%, and the description does not compensate for the many undocumented parameters like rounds, seeding, group_count, points_per_match, advance_per_group, and third_place_match. It partially compensates but leaves 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 states with a specific verb+resource: 'Generate (or regenerate) the draw and schedule.' It also clearly differentiates the tool from siblings by describing it as 'the start action' that moves the tournament from setup to active and closes self-signup.

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

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

Explicit when-to-use guidance is provided: call when the organiser says 'start the tournament'. It details the preview/confirm workflow, the condition for discarding results (requires both confirm:true and discard_results:true), and points to record_feedback as an alternative for unsupported formats.

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. The description adds valuable behavioral context: newest-first ordering, pagination via before_id, and that IDs are global with gaps. These details go beyond the annotations and help set expectations about the data returned.

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: two short sentences that front-load the purpose and then add pagination details. Every sentence adds value, with no fluff or repetition of schema annotations.

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 doesn't need to explain return values. It covers purpose, pagination, and ID behavior. It could be more explicit that the log is scoped to the specified tournament, but that is implied by the required tournament_key. Overall, it is sufficient for a simple read-only listing 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 only 33% (only tournament_key described). The description compensates by explaining before_id as a pagination token and noting that IDs are global with gaps. Limit is not described, but its constraints are in the schema and its meaning is self-evident.

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 it provides a 'chronological record of every change (newest first)' and positions it as the answer to 'who changed that?'. This specific verb+resource combination distinguishes it from sibling tools like get_results or get_schedule.

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 implies when to use the tool (when you need to see change history or who changed something), but it does not explicitly mention alternatives or when not to use it. The context is clear but lacks exclusions or explicit alternative 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 doesn't need to repeat safety guarantees. The description adds value by explaining the tool returns a compact aggregated snapshot, which is consistent with the read-only annotation. It doesn't contradict any annotations and provides useful context about the scope of data included.

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 long, with the first sentence front-loading the tool's purpose and components, and the second providing usage guidance. Every word contributes meaning, with no filler or redundancy. 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?

The description is complete given the existing schema and output schema. It specifies exactly what data the briefing includes, making it clear what the agent can expect. Combined with annotations and sibling context, the agent can confidently select and invoke this tool without further information.

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 fully documents the single parameter (tournament_key) with a clear description and example format. The description adds no additional parameter-level detail beyond noting it's 'just the key', which is already covered by the schema. With 100% schema coverage, a baseline score 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 tool provides a 'compact full state' of the tournament, listing specific components (settings, roster, progress, next matches, standings, page link). This distinguishes it from sibling tools like get_standings or list_matches, which focus on individual aspects. The verb 'get' and resource 'briefing' are unambiguous.

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 explicitly instructs to 'Call this first when resuming work in a new conversation with just the key.' This gives a clear when-to-use directive and prioritizes it over alternatives. It implies the tool is the initial context-gathering step, making the usage scenario very clear.

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 agent knows this is a safe read operation. The description adds value by specifying the payload contents (players, draws, results) and that it is 'full' and 'structured', which are useful behavioral details beyond the annotations.

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

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

The description is a single sentence that front-loads the core action and content, followed by a brief usage note. Every word earns its place with no redundancy or fluff.

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 simplicity (one parameter), an output schema, and read-only annotations, the description fully covers the tool's purpose, content, and usage context. It does not need to explain return values because the output schema exists, and sibling distinctions are clear.

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 a clear description for the only parameter (tournament_key). The description does not add further parameter-level detail, so the baseline of 3 applies; the schema already carries the load.

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 'Full structured export of the tournament document (players, draws, results)' with a specific verb (export), resource (tournament document), and content scope. This distinguishes it from siblings like get_results (specific data) and get_pdf (PDF format), making the tool's purpose unambiguous.

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 clear context ('for the organiser's own records or data portability') that implies when to use it, but does not explicitly name alternatives or state when not to use it. It is better than no guidance but stops short of explicit exclusions like 'use get_results for a single section'.

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 adds valuable behavioral context beyond the readOnlyHint annotation: it returns base64 embedded data, explains the default 'sheet' document (merged tournament document), and notes that 'results' and 'plan' are deprecated pre-merge variants. This is richer than typical annotation-only transparency.

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

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

The description is concise and front-loaded with the core purpose, followed by usage guidance and parameter details. Every sentence contributes essential information without redundancy, making it highly efficient.

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 presence of an output schema and annotations, the description fully covers the necessary context: when to use, what it returns, the default document, deprecated options, and an alternative. No gaps remain for a decision-making agent.

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 description provides semantic meaning for the 'doc' parameter that the schema lacks, including the default value and deprecated variants. The tournament_key is already described in the schema, so the description complements rather than repeats. Since schema coverage is 50%, the description adds significant value for the undocumented parameter.

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

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

Clearly states the tool returns the printable PDF as a base64 embedded resource, which is a specific verb+resource pairing. The description distinguishes it from get_pdf_link and explains the default document type, making its purpose unmistakable.

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 provides when-to-use guidance: 'use this when the organiser wants the file handed to them and your client cannot fetch URLs.' It also names the alternative get_pdf_link for lighter responses, giving clear criteria for 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?

Annotations already establish the tool is read-only and non-destructive. The description adds valuable behavioral context by explaining that pdf_url is the canonical merged document while results_pdf_url and plan_pdf_url are deprecated pre-merge variants kept for comparison. This goes 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 concise and front-loaded with the primary purpose ('Download links for the printable PDF') followed by essential details about the URL fields. Every sentence contributes useful information without any 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 is complete enough for a simple link-retrieval tool with good annotations. It explains the meaning and intended use of each URL field, which is sufficient since the output schema exists and would provide structured field definitions. It lacks only an explicit pointer to alternative tools like get_pdf for the actual file.

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 parameter tournament_key, so the schema already documents the parameter completely. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score 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 tool returns 'Download links for the printable PDF' and specifies the role of each URL. It uses a specific verb+resource construction, but it does not explicitly distinguish itself from the sibling get_pdf tool, so it lacks explicit sibling 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?

The description provides clear usage context by indicating that pdf_url is the merged document to 'hand this to the organiser' and that the other URLs are deprecated comparison variants. However, it does not explicitly state when to use this tool versus alternatives like get_pdf, so it falls 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?

Beyond the annotations (readOnlyHint, destructiveHint), the description discloses the return format (download link and attachable file), confirms no key/parameter is needed, and explains that the tool does not parse filled-in sheets—the agent must handle that. This adds significant behavioral context without contradicting 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 three sentences, each carrying distinct value: first defines the deliverable, second gives usage triggers, third covers behavioral notes. It is concise, well-structured, and front-loaded with the most important 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?

Despite the tool's simplicity, the description covers all necessary aspects: the deliverable, usage scenarios, return format, and follow-up instructions. The presence of an output schema means return value details are outside the description's scope, but the description still goes beyond expectations.

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 has zero parameters, so the schema is trivial. The description explicitly states 'Needs no key,' reinforcing that no input is required and eliminating any ambiguity about invocation.

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 that the tool returns a blank Excel workbook template for the player list, specifying the columns and formatting. This distinguishes it from sibling tools like get_export or get_pdf by naming the specific deliverable and its structure.

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 explicitly states when to offer this tool: when the organiser has no list ready, asks how to send players, or prefers spreadsheets. It also directs the agent to parse a filled-in sheet itself and use add_players, providing clear alternation 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 and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context by noting that for a tournament that ended early, it returns 'placements-so-far,' which is not obvious from the annotations or schema. This extra detail enhances transparency.

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, concise sentence that efficiently conveys the primary purpose and the key edge case. Every word adds value, and there is no redundant or vague phrasing. It is well-structured for a simple tool.

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

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

For a read-only tool with one parameter and an output schema, the description covers the essential purpose and a notable behavioral edge case. It does not explain the return format, but the output schema exists to provide that detail. The description is sufficiently complete for the tool's simplicity.

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 for the single parameter tournament_key, including a clear description that it starts with 'tk_'. The tool description does not add any additional parameter semantics beyond what the schema already provides, so the baseline score 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 tool returns final placements, with the nuance of placements-so-far for early-ended tournaments. It is specific about the resource (placements) but uses a noun phrase rather than an explicit verb, slightly reducing clarity. It distinguishes from sibling tools like get_standings by focusing on 'final' results.

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 implies this tool is used when final placements are needed, including early-ended tournaments. However, it does not explicitly mention when to use it over alternatives like get_standings or get_schedule, nor does it state any exclusions. The usage context is clear but not fully elaborated.

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, establishing a safe read operation. The description adds that results are upcoming matches in playing order, which is useful context but does not disclose additional behavioral traits like default limits or pagination. Given annotations cover safety, a score of 3 reflects modest added value.

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, short, direct sentence with no filler. It efficiently conveys the tool's core function and output characteristics without wasted words.

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 tool has a required tournament_key, an optional limit, and an output schema. The description explains the primary return value but omits details like default date range or limit behavior. Given the output schema and annotations, it is mostly complete for a simple read-only tool, but leaves minor 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?

The schema documents tournament_key but leaves limit without a description. The description does not mention either parameter, nor does it explain how limit affects the result set. With schema coverage at 50% and no compensation from the description, this is a significant 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 clearly states the tool returns upcoming matches with specific attributes (playing order, courts, estimated times). This distinguishes it from siblings like get_results (finished matches) and get_standings (points tables). The verb is implied by the title 'Get,' but the purpose is unambiguous.

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 such as list_matches or get_results. No prerequisites, exclusions, or alternative tool suggestions are provided. The description only describes output content, leaving the agent to infer usage context.

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 safe read-only behavior. The description adds meaningful behavioral detail by specifying the tiebreak ordering (wins → head-to-head → set diff → game diff; americano: total points), which is not present in annotations or schema.

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 dense sentence fully conveys the tool's output and ordering rules. No wasted words; highly 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?

The output schema already specifies return structure, and the description covers behavioral nuances (grouping, tiebreaks) that matter for interpretation. With a single well-documented parameter, this is 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 coverage is 100% and the parameter description is clear ('tournament_key' starts with tk_). The tool description does not add any extra meaning beyond the schema, so the baseline score 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 tool provides current standings per group/structure, with explicit tiebreak ordering. This distinguishes it from sibling tools like get_results (match results) and get_schedule (fixtures).

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 clear context (standings data) but does not explicitly compare to alternatives or state when not to use it. The purpose is obvious, but no exclusions or sibling tool references are provided.

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 operation as read-only and non-destructive; the description adds return structure (sides, scores, courts, times), filter capabilities, and pagination behavior (after_match_number). This goes beyond 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?

Two short sentences front-load the core return value and then present filters and pagination. No filler or redundancy.

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 list tool with output schema and annotations, the description covers what is returned, how to filter, and how to paginate large tournaments. Missing details like default ordering are not essential given the output schema and schema constraints.

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

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

Only tournament_key is described in the schema (20% coverage). The description compensates by explaining the semantics of state (filter), round (filter), and after_match_number (pagination). Limit is self-explanatory with schema min/max, so overall good.

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 title 'List matches' plus description 'Matches with sides, scores, courts and times' clearly identifies a read/list operation for match details. It distinguishes from siblings by mentioning filters and pagination, though it lacks an explicit verb in the description and doesn't reference 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?

The description states filters (state/round) and pagination for large tournaments, which implies when to use it. However, it does not explicitly contrast with sibling tools like get_schedule or get_results, so usage guidance is only implicit.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that it returns the 'full roster' with specific fields, which gives some behavioral context (no filtering). However, it does not disclose details like ordering, pagination, or permission requirements, so it remains at the baseline for annotation-covered tools.

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, efficient sentence that front-loads the core action ('Full roster') and packs essential output details. Every word earns its place, making it concise and well-structured.

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 tool with one required parameter, an output schema, and annotations, the description is complete. It states what the tool returns (full roster with specific fields) and the purpose is clear. No additional context is needed for correct invocation.

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 provides 100% coverage for the single parameter tournament_key, including its format (starts with tk_). The description adds no additional parameter information, so the baseline of 3 applies as the schema already handles the semantics.

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

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

The description clearly specifies the verb 'list' and the resource 'players' (roster), and adds the scope ('full') and key fields (status, level, doubles partner). This distinguishes it from sibling tools like add_players or list_matches, making the purpose unambiguous.

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 clear context that this tool returns the full player roster, which implies its use for overview queries. It does not explicitly name alternatives or exclusions, but the purpose is evident enough for an agent to select it for listing players without confusion.

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, aligning with the description of a non-mutating health check. The description adds the context that the response is a 'static confirmation' and that the tool verifies server reachability, providing useful behavioral context beyond the annotations. No contradictions. It does not elaborate on network timeouts or error behavior, but for a simple ping this is sufficient.

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: 'Health check. Returns a static confirmation that the Turnale MCP server is reachable.' Every word serves a purpose, with the tool's function stated immediately. No fluff or redundancy.

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 simplicity, no parameters, an output schema, and clear annotations, the description is fully complete. It covers the tool's purpose and outcome without unnecessary detail. No gaps remain.

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 has zero parameters, and the schema is empty. The baseline of 4 applies since no parameter descriptions are needed. The description adds no parameter details, but there are none to explain.

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 tool as a health check that returns a static confirmation of server reachability. The verb 'returns' specifies the action, and the resource is the MCP server itself. This distinguishes it from all sibling tools, which are domain operations like tournament management.

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?

While the description does not explicitly mention alternatives or exclusions, the purpose is unambiguous: it is a health check. Given the sibling tools are all tournament-specific operations, there is no alternative for this simple connectivity test. The context makes it clear when to use the 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?

Beyond the annotations (readOnlyHint=false, openWorldHint=true), the description discloses that signed-in players are notified by email, which is a meaningful side effect. It also notes the cap-related behavior, adding context not available in the structured data. 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?

The description is only two sentences, front-loaded with the main action, and every word contributes value. It avoids repetition of schema details and stays focused on the tool's purpose and key context.

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 tool is relatively simple, and an output schema is provided, so return values are covered elsewhere. The description addresses the core scenario, the email notification, and the cap alternative. It doesn't discuss edge cases like failure modes, but those are not essential given the tool's simplicity and the presence of other structured context.

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% (tournament_key and request_id have descriptions). The description doesn't explicitly explain the `name` parameter, which lacks a schema description, but the tool's purpose implies it identifies the waitlisted player. Overall, the description adds minimal parameter-level semantic 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?

The description clearly states the action ('Move a waitlisted player onto the active roster') and the specific condition ('when a spot opens'). It distinguishes itself from sibling tools like add_players, remove_player, and replace_player by focusing on the waitlist-to-active roster transition.

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 clear trigger ('when a spot opens') and suggests an alternative for a related scenario ('The cap can be raised with update_settings'). It doesn't explicitly exclude other player-management tools, but the context is sufficient for an agent to know when to choose 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?

The annotations (all false) provide minimal safety info, so the description carries the burden. It adds crucial behavioral guidance: never include player names, contact details, or tournament keys, and describe missing capability in general terms. This goes well beyond the simple write operation implied by readOnlyHint=false.

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 three sentences, each earning its place: purpose, condition, and content constraints. It is front-loaded with the main action and avoids any filler 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?

For a simple feedback-recording tool, the description covers purpose, usage condition, and content constraints completely. An output schema exists, so return values need no explanation. No gaps remain.

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 describes 'feedback' and 'related_tool', and the enum for 'category' is self-explanatory. The description adds practical parameter guidance by instructing that the feedback should be a general summary without personal data, which directly clarifies how to fill the 'feedback' 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 clearly states the tool records a request for unsupported functionality, using specific verbs and resource ('Record a request for something Turnale does not support yet'). It distinguishes this from sibling tools by focusing on roadmap feedback, which none of the tournament/player management siblings handle.

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 usage conditions: 'Call this only when the organiser asked for something unsupported AND agreed to have it noted.' This makes the when-to-use unambiguous, and although no alternative tools are named, the condition inherently excludes cases where the feature is supported.

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 discloses critical behavioral nuances: reinstate clears a result and returns the match to scheduled, corrections simply re-record, and winner is only needed when the score doesn't decide. Since annotations are all false and uninformative, this description carries the full transparency burden and meets it excellently.

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

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

The description is concise yet dense: three sentences cover purpose, score format, outcome options, correction behavior, and winner logic. It is front-loaded with the core action and every sentence earns its place without redundancy.

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

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

Given the tool's complexity (multiple outcomes, correction semantics, winner logic) and the existence of an output schema, the description is remarkably complete. It addresses mis-entry fixes, confirms multi-result support, and aligns with the schema's idempotency note without over-explaining return values.

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?

While the schema only describes tournament_key and request_id, the description adds essential semantics for the results array fields: score format ('6-4 3-6 10-7' or '16-8'), outcome meanings with partial score allowance, and winner interpretation (a|b). This goes far beyond the schema's bare enum definitions.

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

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

The description opens with the specific verb 'Record' and the resource 'results', immediately distinguishing it from read-only sibling tools like get_results or undo_last_change. It also clarifies that it handles one or many results, making the scope unambiguous.

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 clear context on when to use reinstate versus re-recording, and it explains the default outcome ('completed') and partial score allowance for retirements. It does not explicitly name alternative tools or state when not to use this tool, but the actionable guidance within the tool is strong.

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?

Discloses the side effect of regenerating an existing unlocked draw, which is not evident from the annotations or schema. Annotations only indicate non-read-only, and the description adds specific behavioral context about draw regeneration and timing constraints. Could be improved by clarifying behavior for locked draws or mixed param usage, but it goes beyond baseline.

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, densely packed with essential information: action, timing, alternatives, batching, and side effects. No redundant words, and the most critical 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 that an output schema exists, the description focuses on what the tool does, when to use it, and its side effects. It covers the key scenarios: single removal, bulk removal, and timing constraints. The description is sufficiently complete for an agent to select and invoke 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?

The schema describes 3 of 4 parameters (75% coverage), and the description adds meaning beyond this by instructing to use player_names for bulk removal and explicitly warning against one-by-one looping. The description does not explain the singular player_name parameter, but the schema's coverage partially compensates. Overall, it enhances parameter understanding.

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 begins with 'Remove one or MANY players' which clearly specifies the verb and resource. It also adds temporal context ('before any result is recorded') and distinguishes from sibling tools by mentioning alternatives (withdraw_player, replace_player), making the tool's unique purpose unambiguous.

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 states when to use this tool ('before any result is recorded') and when to use alternatives ('afterwards use withdraw_player or replace_player'). Provides additional guidance on batching ('never loop one-by-one'), which is practical 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?

The description discloses important side effects: completed results stay, the change is shown in a specific format, and unknown substitute names are added to the roster automatically. This goes well beyond the sparse annotations (readOnlyHint false, destructiveHint false) and helps the agent anticipate consequences.

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 sentences, front-loaded with the core action, then two situational details. No filler or repetition of schema content. Every sentence carries meaningful 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?

The description covers the two distinct phases, mode selection, result retention, and auto-add behavior. Since an output schema exists, return values are not needed. Minor gaps: no mention of permissions or idempotency, but request_id is documented in the schema and idempotency behavior is implied there.

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 schema coverage at 40%, the description compensates by explaining the mode enum values (slot_swap default vs regenerate), the role of levels in regenerate mode, and the auto-add behavior for names. It doesn't elaborate on out_player_name or request_id, but those are self-explanatory from their schema 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 states a specific action: a substitute takes over a player's spot, with two modes (slot_swap and regenerate). This clearly distinguishes it from sibling tools like remove_player or withdraw_player, which have different semantics.

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 usage context: during play vs before the first result, and explains which mode to choose in each situation. It also notes auto-add behavior for unknown substitutes. It doesn't explicitly name alternative tools, but the situational guidance is clear.

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 this is a write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). The description adds meaningful behavioral context, notably that played matches never move, which is not encoded in annotations. It also reveals three distinct operational modes (time shift, delay, court/slot move).

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 long, front-loaded with the primary actions, and includes a critical constraint without extraneous detail. Every word serves a purpose.

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 nested objects and an output schema, the description covers the main actions and a key constraint. It does not explain the internal structure of move_match or that actions might be exclusive, but these are partially covered by the schema. Overall, it provides sufficient context for a complex 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 coverage is 60%, and the description compensates by explicitly linking the three operations to parameters (start_time, delay_minutes, move_match). It also clarifies the purpose of move_match via 'specific court/slot'. The request_id and tournament_key are explained in the schema, so the description adds value where needed.

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 verb ('Shift', 'add', 'move') with resources ('start time', 'delay', 'match') and scope ('to a specific court/slot'). It distinguishes from siblings like get_schedule by focusing on mutations, and the constraint 'Played matches never move' adds specificity.

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 clear context for when the tool is appropriate (rescheduling matches via time/delay/court changes) but does not explicitly list alternatives or when not to use it. The constraint 'Played matches never move' implies a boundary, though no direct sibling comparison is given.

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

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

The description discloses a key behavioral trait: it regenerates an existing unlocked draw, which implies overwriting current pairings. It also states the temporal constraint ('Only before results exist'). This adds context beyond the annotations, which only indicate readOnly=false and destructiveHint=false. 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?

Two sentences, front-loaded with the core action, followed by key constraints. Every word earns its place; no fluff or repetition. Highly efficient and easy to scan.

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 an output schema and four parameters, the description covers the main functionality, modes, temporal constraints, and regeneration behavior. It does not explain error conditions (e.g., what happens if results exist) or locked draw behavior, but schema and annotations fill some gaps. Overall sufficiently complete for a well-scoped operation.

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 description adds meaning to the parameters by explaining the two modes (explicit pairs vs. auto-pair) and clarifies the 'auto' enum values (random/level-balanced). The schema already documents pairs, request_id, and tournament_key, but the description helps disambiguate the auto parameter beyond the schema. Overall it provides useful semantic 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 uses a specific verb 'Fix' with a clear resource ('doubles pairs') and explains two modes: explicit pairs by name or auto-pairing (random/level-balanced). It also states key constraints ('Only before results exist', 'Regenerates an existing unlocked draw') that distinguish it from sibling tools like swap_partners or generate_draw.

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 clear context on when to use the tool: only before results exist, and it can regenerate an unlocked draw. However, it does not explicitly mention alternatives or when not to use it compared to related tools such as swap_partners, though the constraints imply some boundaries.

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 this as read-only and non-destructive, so the bar is lower. The description adds valuable behavioral context: it explains that round/time math is done by the engine, that omitting `discipline` returns a question instead of a menu, that americano and mexicano are doubles, and that no key is needed. 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?

The description is somewhat long but each sentence carries distinct weight: purpose, when to use, the discipline prerequisite, and a note about key requirements. It is front-loaded and structured with paragraph breaks for emphasis. Slightly dense but not wasteful.

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 covers the core selection and invocation concerns: when to use, the key prerequisite, and expected output. Since an output schema exists, return values need no further explanation. The tool is sufficiently complete for an agent to choose and call it correctly, though the 'Needs no key' phrase is a bit ambiguous.

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 71%, so the schema does most of the work. The description adds important nuance about `discipline` (omitting it changes the response, it must never be inferred), but this is largely repeated from the schema's own description. Other parameters like `players_estimate` and `match_minutes` are not elaborated, so the description only partially compensates.

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 tool's function: 'Recommend tournament formats in plain language, with the round/time math done by the engine.' It also distinguishes itself from sibling tools by emphasizing it should be called FIRST for format selection, and explicitly describes the output as a `menu` to relay. The verb+resource structure is specific and unique.

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

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

Explicit conditions are given: 'Call this FIRST when the organiser has not named a format, names one hesitantly, or comes from a background where americano/mexicano need explaining.' It also instructs to relay the menu text instead of asking open questions, clarifies the discipline prerequisite, and says 'Never infer it from the sport.' This is strong, actionable 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?

The description discloses that fixed-pair swaps are permanent, that Americano/mexicano swaps occur in exactly one unplayed round, and that the preview names any repeated partnership/meeting. This goes far beyond the annotations (readOnlyHint=false, destructiveHint=false), giving the agent a clear picture of the tool's behavior and side effects.

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?

Despite covering multiple formats and workflow details, the description stays tight and well-structured with colons and semicolons. Every sentence carries essential information with no redundancy 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?

It covers both tournament formats, the preview/confirm mechanism, edge cases like a sitting player, and the immutability of played results. Given the output schema exists, it appropriately omits return-value details, yet still gives the agent a complete mental model of when and how to invoke the 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?

It adds meaning to 'round' (only for Americano/mexicano, omit for next unplayed round) and 'confirm' (preview vs apply), which are not fully explained in the schema. It also implicitly clarifies that player_a and player_b represent one player from each pair in fixed-pair mode. With 67% schema coverage, this fills the gap effectively.

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 'Exchange two players' places' and immediately distinguishes between fixed-pair doubles (swaps partners permanently) and Americano/mexicano (swaps places in one unplayed round). This specific verb+resource+scope clearly differentiates it from sibling tools like replace_player or set_pairs.

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

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

It explicitly frames the tool as the 'courtside patch for a late arrival, an injury, or two friends who want a game together,' and clarifies both format-specific usage and the constraint that 'Results already played never move.' It also instructs to 'Preview first, confirm to apply' for a safe workflow.

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

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

Annotations already declare destructiveHint=true, and the description adds substantial behavioral detail: what gets discarded (the change and everything later), how preview works before applying, and that a follow-up undo restores the previously discarded changes. It also notes that changes can come from tool calls or courtside page entries, providing context beyond the annotations. This richly informs the agent about consequences and state transitions.

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

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

The description is concise yet comprehensive, with a clear structure: overview sentence, conditional behavior for the two modes, preview/confirm explanation, and the redo follow-up note. Every sentence earns its place, and the information is front-loaded, making it easy for an agent to parse quickly.

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 tool is complex with multiple modes, a preview mechanism, and a redo behavior. The description covers all these aspects and provides necessary context about change tracking origins. It references get_audit_log for obtaining change IDs, which integrates well with sibling tools. Given the rich output schema and annotations, the description is complete enough for the agent to use 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?

The input schema already provides 100% parameter coverage with clear descriptions. The description reinforces the semantics of to_change_id and confirm but does not add significant new meaning beyond what the schema states. Since schema coverage is high, a baseline of 3 is appropriate; the description adds minimal extra value for parameter understanding.

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 tool's purpose with a specific verb ('Roll the tournament back') and identifies the resource (tournament state). It distinguishes between two modes (undo latest vs. undo to a specific change), which differentiates it from any potential sibling tools. The reference to get_audit_log for obtaining change IDs further clarifies its role within the toolset.

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 clear usage context: when to omit to_change_id (undo most recent change) and when to include it (undo a burst of unwanted changes). It also explains the preview/confirm flow and the redo behavior. While it doesn't explicitly list alternative tools, the conditions for use are well-defined and sufficient for the agent to decide when to invoke 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?

The description discloses atomicity: "The whole batch applies or none of it does," a critical behavioral trait not captured in the annotations. It also explains the historical pain point of partial updates, adding valuable context beyond the readOnly/destructive hints.

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 four sentences and front-loaded with purpose. The anecdote about phone approvals is slightly verbose but serves as a memorable justification for the batch design. Overall, it is concise and each sentence adds value.

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

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

Given the tool's complexity (8 params, nested array objects), the description covers the key behavioral aspects: batch usage, atomicity, and the single-vs-multiple dichotomy. It does not address potential edge cases like mixing top-level and array updates, but the output schema and detailed parameter schema fill some 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 75%, so the baseline is 3. The description adds some value by explaining the `updates` array pattern, but it does not clarify the relationship between top-level fields and the updates array, or explain the `new_name` parameter. The schema already covers most parameter meaning.

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

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

The description opens with a specific verb and resource: "Rename a player or set their gender/level/note." It clearly distinguishes itself from sibling tools like add_players or remove_player by focusing on updating existing players, and the batch capability further clarifies its unique role.

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 provides direct usage guidance: "never loop one-by-one" and "pass `updates` with one object per player," which is a clear directive for batch use. While it doesn't explicitly name alternatives, it implicitly advises against an inefficient pattern and sets expectations for the batch workflow.

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

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

Annotations already flag this as a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds value by disclosing a key side-effect: court changes recompute the remaining schedule, and played matches never move. This goes beyond the annotations and helps the agent anticipate consequences.

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, front-loaded with the core purpose and followed by the critical behavioral caveat. Every clause earns its place; no filler or redundant repetition of schema 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 complexity (18 parameters), the description covers the main changeable settings and one important behavioral side-effect. Detailed parameter semantics are delegated to the schema, and an output schema exists. It doesn't describe prerequisites like the required tournament_key, but the schema covers that. Overall, it is complete enough for an agent to select and invoke 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 coverage is 67% and many parameters already have detailed descriptions (e.g., level_scale, request_id, page_results_entry). The description reinforces the mapping between prose terms and specific fields (e.g., 'courts (count or names)' -> courts and court_names, 'break/changeover minutes' -> break_minutes), which improves semantic clarity beyond the raw 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 opens with a specific action ('Change') and enumerates the resources: tournament name, start time, match duration, break/changeover minutes, courts, house rules, and courtside score entry. This clearly distinguishes it from sibling tools like update_player or generate_draw, which target other entities.

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 makes it clear that this tool is for altering tournament settings, and the listed fields provide context for when to use it. It doesn't explicitly name alternatives or exclusions, but the scope is unambiguous given the sibling list and the specific domain.

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

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

With annotations providing no safety hints (all false), the description carries the burden of behavioral disclosure. It explains the impact on remaining matches (walkovers) and format-specific behavior (americano regenerates future rounds), and emphasizes the preview/confirm mechanism. This is valuable context beyond the schema's parameter descriptions.

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 long and front-loaded with the primary action, followed by behavioral consequences and a usage note. Every sentence earns its place with no redundancy or fluff.

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 covers the essential outcomes (walkovers, americano regeneration) and the preview/confirm workflow, which is central to this tool. It doesn't discuss prerequisites or error scenarios, but the output schema exists and the parameter schema is well-documented, so the description is sufficiently complete for an agent to use 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 75%, so most parameters are documented. The description adds context for 'confirm' ('Preview first, confirm to apply') but this is already detailed in the schema. It doesn't clarify 'player_name' beyond indicating a player or pair. Overall, the description adds marginal value over the schema, 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 tool's function: 'Withdraw a player (or their pair) mid-tournament.' This is a specific verb-and-resource description. It doesn't explicitly compare to sibling tools like remove_player or replace_player, but the mention of tournament consequences (walkovers, americano rounds) helps distinguish it from simple removal.

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 clear usage context: withdrawing a player mid-tournament, with a preview-first workflow ('Preview first, confirm to apply'). It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to decide when to invoke it.

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