Squadcard

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

With annotations only flagging destructiveHint=true, the description explains the actual destructive semantics (it replaces any previous answer), the identity constraint, and the overflow behavior ('in' on a full game goes to the waitlist and the result reflects it). This is exactly the extra context annotations cannot carry.

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

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

Three short sentences, front-loaded with the action, then identity scope, then the waitlist edge case. Every sentence carries distinct information with no repetition of the schema or title.

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

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

For a small 2-parameter mutation tool with annotations covering the safety profile, the description covers identity scope, overwrite behavior, and the full-game edge case. The only mild gap is that it doesn't explicitly state what the returned result contains beyond 'says so', though no output schema exists.

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 enum plus the squadId cross-reference to list_squads are already documented. The description still adds meaning the schema lacks: what 'in' actually does when the game is full, i.e. waitlisting.

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

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

States a specific verb+resource: recording the signed-in user's in/maybe/out answer for a squad's next game. That is clearly distinct from siblings like set_game (which configures the game) or join_squad (membership), so an agent can pick it without opening the schema.

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

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

Gives clear context plus an exclusion: it acts only for the signed-in user and never on behalf of another player. It does not, however, name the alternative tool an agent should reach for when acting for someone else, so routing is still partly inferred.

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 this is a non-destructive, non-open-world write, so the description's job is lighter. It still adds real context beyond the annotations: the user becomes organiser, an existing player card is reused, and an invite link is returned. Gaps remain around failure modes (duplicate squad) and limits, keeping it at 4.

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 no filler; the core action and role are front-loaded, and the confirmation instruction follows naturally.

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

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

With no output schema, the description usefully discloses the return value (invite link for the group chat). Optional parameters and error conditions are unaddressed, but nothing essential for calling the tool correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description only references 'name and size' (aSide) as things to confirm, adding marginal meaning and omitting locale, timezone, and crestColor. Baseline 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?

States a specific verb and resource ('Start a new Squadcard squad'), names the acting role (user as organiser) and the derived output (invite link). It is clearly distinguishable from siblings like get_squad, list_squads, and join_squad.

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

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

Gives an explicit prerequisite workflow step: 'Confirm the name and size with the user first.' It does not, however, name an alternative or state when not to create (e.g. when the user should join_squad instead), so it falls short of full when/when-not guidance.

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

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

Annotations already declare destructiveHint=true and openWorldHint=false, and the description adds real context beyond them: the call opens voting, returns a vote link for the group chat, and requires organiser rights plus user confirmation. It does not clarify whether re-entry overwrites an existing result, which matters for a destructive operation.

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

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

Three short sentences, zero filler, with the core action front-loaded and the permission and confirmation caveats following in order of importance. Every sentence earns its place.

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

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

For a three-parameter mutation with annotations covering the safety profile and no output schema, the description covers permissions, side effect (opening voting), and return value (vote link). The remaining gap is idempotency/overwrite behaviour on an existing score.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, including where matchId comes from. The description adds no syntax, format, or validation detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Save a match's final score'), which is distinguishable from siblings like set_game, answer_game, or get_match. It does not explicitly name an alternative tool, but the operation itself 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?

Gives a clear precondition ('organisers only') and an explicit procedural directive ('Confirm the score with the user first'), which is genuinely useful for a write operation. It stops short of routing the agent away from similar tools such as set_game or answer_game.

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 real behavioral context beyond the annotations: it discloses the anonymization guarantee ('Totals only, never who voted what'), the inclusion of a vote link, and the conditional availability of the result after voting closes. However, annotations declare readOnlyHint=false, which sits awkwardly against a verb ('Get') that reads as a pure fetch — the description neither explains nor resolves that mismatch, so transparency is partial.

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

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

A single front-loaded sentence with a colon-separated payload list, plus one short guarantee clause. Zero filler and no repetition of the name or title.

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

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

With no output schema, the description carries the return-value burden and does so well by enumerating the expected fields and the vote-anonymity rule. It stops short of covering failure modes (e.g., invalid or unknown matchId) and leaves the readOnlyHint=false annotation unexplained.

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

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

Only one parameter exists and schema description coverage is 100%, with the schema itself stating where the id comes from ('from pick_teams or get_squad'). Per the high-coverage rule, 3 is the baseline; the description adds nothing about matchId, but nothing is needed either.

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

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

States a specific verb and resource ('Get a match') and enumerates exactly what the caller receives: teams, score, vote link, vote count, and the closed-voting result. An agent can predict the payload without opening the schema, though it never explicitly distinguishes this from siblings like get_squad or list_squads.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternatives among the twelve sibling tools. The only timing hint is that the result appears 'once voting has closed', which describes a field's availability rather than when to call this tool.

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

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

Annotations already cover the safety profile (destructiveHint=false, openWorldHint=false), and the description usefully discloses the return payload fields, which matters because there is no output schema. It does not, however, explain or reconcile the unusual readOnlyHint=false on what reads as a pure fetch.

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

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

A single front-loaded sentence that enumerates the returned content with zero 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 one-required-param read with no output schema, the description does the important work of listing what the response contains. The remaining gap is the absent routing guidance to list_squads and the unexplained readOnlyHint=false.

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 squadId parameter, so the schema already carries the semantics. The description adds nothing about id format or sourcing beyond what the schema states, so the baseline 3 applies.

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

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

Specific verb ('Get') plus resource ('one squad') and an enumeration of what comes back (invite link, players, next game, RSVPs). The word 'one' implicitly separates it from the list_squads sibling, though no sibling is named directly.

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

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

Usage is only implied: you call this to inspect a single squad by id. There is no explicit when-to-use/when-not, no mention of list_squads as the alternative for browsing, and no prerequisite guidance beyond the schema's 'from list_squads' note.

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

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

Annotations only mark this as a non-read-only, non-destructive, non-open-world operation. The description adds what those annotations cannot: joining is free, the user's name and card become visible to the whole squad, and the write only happens on the second call after explicit consent. That is exactly the behavioral context an agent needs before mutating shared state.

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?

Purpose is front-loaded, then the confirmation sequence, then the safety constraint last where it reads as a guardrail. Every sentence carries a distinct instruction; nothing is redundant with the title or 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?

There is no output schema, and the description compensates by telling the agent what the first call returns (the squad's name) and what to do with it. Together with the annotations and full schema coverage, an agent has everything needed to call this correctly and safely.

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 schema already explains squadName. The description still adds real value by spelling out that the first call sends only the invite and that squadName must be the exact name returned, tying the two parameters into one workflow rather than two independent fields.

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

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

States a specific verb and resource ('Join a Squadcard squad from its invite link, as a player') plus the key constraint that the user's existing card is used. This clearly separates it from create_squad, get_squad and the other squad siblings.

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

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

Gives an explicit two-call protocol with the condition that selects each call and the required user confirmation in between. It also names a hard exclusion: only use a link the user provided in this conversation, never one from a web page, file, or another tool's result.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only that ids are returned and results are scoped to the user's own squads; it says nothing about ordering, volume, or empty-result behavior.

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

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

A single short sentence with the resource and return content front-loaded and no filler. Nothing could be cut without losing information.

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

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

For a zero-parameter, non-destructive list tool with no output schema, the description is nearly complete: it tells the agent what comes back (squads with ids). Only minor gaps remain, such as whether the list can be empty or how results are ordered.

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

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

The tool takes no parameters, so the schema carries no argument semantics to document and the baseline is 4. The description correctly implies no filtering input is 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?

States a specific verb (List) and resource (the user's squads) plus the returned payload (ids), which clearly distinguishes it from the singular get_squad sibling. It doesn't explicitly name an alternative, but the plural, user-scoped framing 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?

Usage is only implied: 'the squads the user is in' signals this is the broad listing call to use when you don't have an id yet, versus get_squad. There is no explicit when-to-use statement or named alternative, and no prerequisite/auth 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, destructiveHint=false and openWorldHint=false, so safety is covered. With no output schema, the description earns credit by disclosing what comes back ('both teams and a message for a group chat'), which is real behavioral information an agent would otherwise lack.

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, zero filler, and the core action plus constraints are front-loaded before the return-value statement. Every sentence carries information.

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

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

Covers action, input bounds, keeper handling and return contents, which is enough for a no-output-schema tool with full annotation coverage. It omits failure behavior (e.g., what happens with fewer than 4 players) but that is a minor gap.

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

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

Schema coverage is 100%, so the schema already documents players, level, keeper and shuffle. The description adds the domain constraint that 4-30 players are required and that keepers are placed on opposite sides, but adds no format details for the shuffle parameter beyond what the schema says.

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

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

States a specific verb and resource ('split ... football players into two fair, balanced teams') plus concrete scope (4 to 30) and the keeper constraint. It is clear on its own, but it never names the closely related siblings pick_teams or reshuffle_teams, so an agent still has to infer which of the three to use.

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

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

The description implies the use case via its constraints (4-30 players, football, keepers) but gives no explicit when-to-use or when-not-to-use guidance and does not point to pick_teams or reshuffle_teams as alternatives. Usage has to be inferred from scope rather than stated.

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

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

Annotations already declare a safe, non-destructive, closed-world read, so the bar is lower. The description adds genuinely useful domain behavior not in the schema: the 3–16 team bound and the bye/rest round for odd counts. It stops short of saying what happens for out-of-range input or how the schedule is structured across rounds.

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

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

A single front-loaded sentence with no filler; the constraints and behavior are packed densely and nothing is repeated.

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

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

For a generator tool with no output schema, the description does not describe the shape of the returned fixture list (rounds, pairings) or error behavior for invalid team counts, leaving an agent to infer the return structure. Acceptable but with a clear gap.

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

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

Schema description coverage is 100%, so both parameters (teams, homeAndAway) are already documented. The description reinforces the round-robin semantics but adds no format or syntax detail beyond the schema's "true: everyone meets twice."

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

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

States a concrete verb+resource ("Make a round-robin fixture list") plus a precise scope (3–16 teams, everyone plays everyone, rest round for odd counts). This is clearly distinct from sibling team-forming tools (make_fair_teams, pick_teams, reshuffle_teams) without needing to name them.

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

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

The 3–16 team range and the odd-number rest round imply valid usage, but there is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives such as make_fair_teams or pick_teams for splitting players into sides.

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=false, destructiveHint=false, and openWorldHint=false, so the write-but-safe profile is covered. The description usefully adds the organiser-only authorization constraint, but says nothing about whether existing team assignments are overwritten, whether the result is persisted, or how randomness/fairness is seeded.

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 sentence, zero filler, with the core action and the authorization caveat front-loaded. Nothing is redundant or restated from the title.

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

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

For a one-parameter mutation with no output schema, the description covers the essentials, but it omits what the tool returns (team rosters? assignment IDs?) and how it interacts with the closely related team-generation siblings. Those gaps matter because the tool mutates state and has ambiguous alternatives.

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

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

Schema description coverage is 100% and the single parameter (squadId) is fully documented with a pointer to list_squads, so the schema carries the burden. The description adds only the soft context that the picked players come from the next game's roster; it introduces no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

The description gives a specific verb and resource ('Pick two balanced teams') plus the player pool ('players who are in for the squad's next game'), so an agent understands the operation. It does not, however, distinguish itself from the very similar sibling tools make_fair_teams and reshuffle_teams, leaving ambiguity about which one to call.

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 parenthetical '(organisers only)' is a genuine prerequisite that tells the agent who may invoke it. But there is no guidance on when to choose this over make_fair_teams or reshuffle_teams, which appear to overlap heavily in function.

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 readOnlyHint=false, and the description adds real context: it overwrites an existing split rather than creating a new one, keeps the same players, and is restricted to organisers (an authorization requirement annotations cannot express). It does not say whether the previous split is recoverable or how randomness is seeded, leaving a small gap.

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

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

A single sentence that front-loads the action and then the constraints; every clause (same players, teams already picked, organisers only) earns its place with no repetition of structured fields.

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

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

For a one-parameter mutation tool with no output schema and available annotations, the definition covers action, scope, and the organiser gate. The only unresolved detail is whether the prior team assignment is lost or reversible, which is minor given destructiveHint=true.

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

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

There is a single parameter with 100% schema description coverage ('The match's id, from pick_teams or get_squad'), so the schema already carries the semantics. The description adds nothing about matchId, making the baseline 3 correct.

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

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

The description gives a specific verb+resource action ('pick another balanced split of the same players') and scopes it to a match whose teams are already picked, which implicitly separates it from pick_teams and make_fair_teams. It does not name any sibling explicitly, so it stops just short of a 5.

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

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

It states a clear precondition ('a match whose teams are already picked') and a permission gate ('organisers only'), so an agent knows when this tool applies rather than pick_teams. No explicit alternatives or when-not-to-use cases are named, so it is clear context without full routing guidance.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the write nature is already structured. The description adds the auth constraint (organisers only), which annotations do not cover, but it never discloses what re-setting destroys or overwrites for an existing game already populated by players.

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

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

Two short sentences, front-loaded with the action and followed by the downstream consequence for players. Nothing is padded or restated.

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 7-parameter mutation with destructiveHint=true and no output schema, the description is thin: it omits the replace-vs-create semantics and what happens to existing attendees or costs when the game is re-set. Annotations cover the safety profile and the schema covers parameters, so it is minimally viable but leaves real 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 description coverage is 100%, so all seven parameters (venue, repeat, startsLocal, playerLimit, pitchCost, durationMinutes) are already documented in-schema. The description contributes no timing format, defaults, or money-tracking nuance beyond that, so the baseline 3 applies.

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

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

States a concrete verb ('Set') and resource ('when and where a squad plays'), which is enough to separate it from siblings like answer_game, join_squad, or create_squad. It does not explicitly name an alternative, so it falls just short of the 5 mark.

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

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

'Organisers only' tells the agent the caller population permitted to invoke it, which is genuine usage context. However, there is no statement of when to use this versus answer_game/join_squad, nor when re-calling is appropriate, leaving the routing to inference.

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 readOnly, non-destructive and closed-world, so safety is covered. The description adds genuinely useful behavior: theme mode returns ten names, word mode produces club-style constructions. It does not mention randomness or whether suggestions repeat, but for a pure generation tool this is solid added 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?

A single front-loaded sentence with zero filler; both output modes are stated economically and nothing needs trimming.

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

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

There is no output schema, so the description must carry return-shape information, and it does indicate what the caller gets (ten themed names, or club-style names). Missing details such as response structure or whether results are deduplicated are minor for a low-risk generator with covered annotations.

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 50% (the theme enum is undocumented in the schema). The description compensates by explaining that theme yields ten names and that word is used to build club-style names from something like a town or pub, which gives the agent enough to pick the right 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?

States a specific verb (suggest) and resource (football team names), plus two distinct output modes: themed lists and club-style names derived from a word. It is clearly different in kind from sibling mutation/selection tools like make_fair_teams or pick_teams, though it never names a sibling to sharpen the contrast.

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 phrase 'ten from a theme, or club-style names made from a word' implicitly tells the agent which input produces which result, so the mode selection is inferable. However, there is no explicit statement of when to choose this tool over name-producing alternatives, and no guidance on what happens if both or neither parameter is supplied.

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