Squadcard

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

Annotations flag destructiveHint=true, and the description explains exactly what that means: it 'replaces any answer they gave before.' It also discloses the overflow behavior that 'in' returns a waitlist placement when the game is full and that the result reports this, plus the signed-in-user-only scope constraint.

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 scope restriction, then the destructive/waitlist caveat. Every sentence adds information an agent needs; there is no filler.

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

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

For a two-parameter mutation with full annotation coverage and no output schema, the description covers action, scope, replacement semantics, and waitlist outcome. It stops short of stating eligibility/prerequisite conditions (must be a squad member, answer window) before the call will succeed.

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 enum values are self-explanatory, so the schema already does the heavy lifting. The description's waitlist note adds behavioral meaning to the 'in' value but nothing about squadId beyond the schema's 'from list_squads' hint.

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 ('Say whether the user is in, maybe or out for a squad's next game') and no sibling tool performs this action, so an agent can distinguish it immediately. The three allowed answers are named inline, matching the enum.

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 bounds usage: it answers only for the signed-in user, never another player, and notes there is no other-player tool because each player answers from the squad's page. That is strong when-to-use guidance, though it does not say what prerequisite state (e.g. squad membership, game not yet played) must hold.

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 declare it is a non-read-only, non-destructive, closed-world write. The description adds real behavioral context beyond that: every call creates a new squad even with a duplicate name, and two specific failure conditions (no player card, no Squad Pro seat) with a reason and link 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?

Three tightly-packed sentences, front-loaded with the action and return value, then the confirmation guidance, then the duplicate-call and failure-mode warnings. No sentence is redundant.

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 compensates by naming the return value (invite link) and the error shape (reason plus link). Combined with full parameter coverage, an agent has everything needed to call it correctly and interpret a failure.

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 including aSide's 3-11 range and timezone format. The description only alludes to 'name and size', which adds negligible meaning over the schema, so the 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'), plus who becomes organiser and what is returned (the invite link). It is clearly distinguishable from siblings like join_squad, get_squad and 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?

Explicitly states when to use it ('Confirm the name and size with the user first') and, more importantly, when NOT to repeat it, naming list_squads as the way to check existing squads before creating a duplicate.

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 a non-read-only, destructive operation, and the description goes well beyond them: it discloses the authorisation requirement (organisers only), the state transition that opens voting, the returned vote link, the replace-not-append semantics of repeat calls, and the hard immutability boundary once voting closes. The 'confirm with the user first' instruction is exactly the kind of caution an agent cannot infer from structured fields.

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

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

Four sentences, front-loaded with the purpose, then the lifecycle, then the safety instruction. Every sentence carries a distinct behavioural fact (authorisation, voting trigger, idempotency, immutability) with no repetition or filler.

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

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

With no output schema, the description compensates by naming the vote link that the first call returns. For a three-parameter mutation tool with a state machine behind it, all the information an agent needs to call it safely and correctly is present.

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

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

Schema coverage is 100%, so scoreA, scoreB and matchId are already documented (including that matchId comes from pick_teams or get_squad). The description adds no scoring 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') plus the two scoping conditions that define it: organisers only, and only after kick-off. This clearly separates it from setup-time siblings like set_game, make_fixtures and pick_teams without needing the schema opened.

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 (organisers only, after kick-off) and spells out the full call lifecycle: first call opens voting and returns the vote link, repeat calls correct the score without touching voting, and calls after voting closes are rejected. It also instructs the agent to confirm the score with the user before calling. No alternative tool is needed, and the exclusions are stated rather than implied.

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?

Unusually good: it pre-empts the confusing readOnlyHint=false by explaining that returning the vote link can close a vote when time is up, and it states the privacy scope (aggregate totals, never individual votes). It stops short of noting pagination or error cases, and for a single-match fetch those are minor.

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, each carrying distinct load: return contents, the routing precondition, then the read-only caveat. Nothing is padded and the caveat is front-loaded well before it could cause a wrong call.

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 by enumerating the payload fields and the aggregation granularity. The side effect on vote closure is disclosed, leaving nothing an agent needs before calling.

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 matchId description already names pick_teams and get_squad as sources, so the description's restatement adds no new syntax or format detail. Baseline 3 for a one-param tool whose schema does the heavy lifting.

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

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

Names the resource and enumerates exactly what comes back: teams, score, vote link, vote count, and result once voting closes. It also draws the boundary against siblings by tieing its use to pick_teams, enter_result, and get_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 explicit entry points: call it after pick_teams or enter_result, or feed it a matchId obtained from get_squad. An agent can route to it without inference or opening another schema.

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 say readOnlyHint=false without explaining why. The description supplies the crucial non-obvious side effects: it returns the invite link and opening a squad closes a vote whose time is up. This is exactly the kind of behavioral context annotations cannot convey.

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

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

Three sentences, front-loaded with what is returned, then usage, then the caveat. The 'It changes nothing you asked for, but it isn't marked read-only' clause is slightly convoluted but earns its place by flagging the side effect.

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 compensates by enumerating the returned fields, and it covers usage routing and the non-read-only side effect. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100% and the single squadId parameter is already documented in the schema as 'The squad's id, from list_squads.' The description adds no syntax or format detail 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 specific verb+resource ('Get one squad') and enumerates exactly what comes back: invite link, players, next game, in/out/maybe responses, and matchId once teams are picked. This clearly separates it from list_squads (plural, filtered) and get_match (single match).

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

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

Explicitly tells the agent when to call it: 'Use it before set_game, pick_teams or answer_game to see where things are.' Names the sibling tools that depend on the state this returns, leaving no inference required.

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 closed-world, so safety is covered. The description adds real behavioral context beyond them: the empty-list semantics ('they aren't in a squad yet') and the ordering dependency on downstream squad tools. It does not describe the shape of a populated result, but with no output schema that gap is minor.

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, each earning its place: identity/return value, invocation trigger, empty-state branch. The most important guidance (call first) 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?

For a no-argument, read-only list tool, the definition covers what is returned, when to call it, and what an empty result implies, routing the agent onward. Nothing needed to invoke it correctly is missing.

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

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

Zero parameters, so the baseline of 4 applies; there is no parameter surface for the description to illuminate or obscure.

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+resource ('List the Squadcard squads the user is in') with scope spelled out, plus the key differentiating detail that the result carries the id other squad tools require. An agent can distinguish this from get_squad (needs a squadId) without opening either 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?

Explicit routing: 'Call it first when you don't have a squadId.' It also names the two alternatives for the empty-list branch (create_squad, join_squad), covering both the when-to-use and the fallback path.

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

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

Goes well beyond the readOnly/non-destructive annotations by disclosing persistence behavior ('needs no squad and saves nothing'), determinism ('the same list always gives the same teams'), and full return shapes (bibs/nonBibs with average ratings, team list, verdict, group-chat message). This is exactly the 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?

Front-loaded with the core purpose, then constraints, alternatives, and return values in a tight sequence. Dense and slightly long for a single paragraph, but nearly every clause carries actionable 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?

With no output schema present, the description fully compensates by describing both return variants and the verdict/message fields, plus the input constraints and no-persistence guarantee. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: player-count constraints per team mode (4-30 for two, 6-30 for three), keeper spreading, and the shuffle parameter's effect on producing a different fair split. Only the teams-mode third-team use case ('winner-stays-on') is extra flavor rather than parameter detail.

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 fair, balanced teams — and immediately names the sibling it is not (pick_teams) for squad-owned games. An agent can distinguish it from make_fixtures, reshuffle_teams, and pick_teams without opening a 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?

Explicit about when to use it (standalone group of 4-30 or 6-30 players, no squad needed, nothing saved) and when not to ('for a Squadcard squad's own game, use pick_teams instead'). It also explains the alternative split route via the shuffle parameter.

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 read-only, closed-world operation, so the bar is lower. The description then adds genuinely useful behavior: the shape of returned rounds ({home, away}, resting or null), the game count, an auxiliary group-chat message, and the refusal-with-reason path. It stops short of describing pagination or ordering of rounds, but the added context is substantial.

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 core scope is front-loaded in the first clause and every subsequent clause carries real information (resting team, return shape, dedup, refusal). It is packed into one long sentence, which slightly hurts scanability, but there is no filler.

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

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

With only two simple parameters and no output schema, the description carries the return-shape burden itself and covers limits, dedup, byes, and error behavior. An agent has everything needed to call and interpret this 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 100%, so the baseline is 3. The description still adds meaning beyond the schema: it clarifies the dedup rule for 'teams' ('repeated names count once'), the valid 3–16 range, and the consequence of odd counts (a resting team each round), which sharpens how 'homeAndAway' interacts with the round structure.

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 ('Make a round-robin fixture list') with its exact scope (3 to 16 teams, everyone plays everyone). It is clearly distinguishable from siblings like make_fair_teams and reshuffle_teams without opening any schema.

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

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

The description supplies strong input constraints (3–16 teams, duplicates collapse, out-of-range names are refused) which implicitly tells the agent when the tool is usable. However, it never contrasts this tool with any sibling such as make_fair_teams or pick_teams, so selection guidance remains inferential.

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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description goes further by disclosing idempotent behavior ('if teams are already picked it changes nothing and returns them'), the authorisation requirement, and the return value (matchId). That is real context beyond the structured fields.

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

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

Three tight sentences, front-loaded with the core action and return value, then the edge case, then the sibling routing. No sentence is filler.

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

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

For a single-parameter mutation with no output schema, the description covers what it does, who may call it, what happens on repeat invocation, and what is returned. Nothing an agent needs in order to call it correctly is missing.

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

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

There is a single parameter and the schema already documents it at 100% coverage, including where to obtain the value (list_squads). The description implies the squad context but adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (pick two balanced teams) with clear scope (players in for the squad's next game, drawn from peer ratings). It explicitly distinguishes itself from sibling tools reshuffle_teams and make_fair_teams, so an agent can route without opening another 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?

Names two alternatives with the exact conditions that select them: reshuffle_teams when a fresh split is wanted, make_fair_teams when there is no squad. It also states the organisers-only prerequisite, leaving nothing 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 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?

Beyond the destructiveHint=true annotation, the description discloses exactly what gets destroyed (omitted fields revert to defaults: no venue, no cost, no player limit) and advises passing everything that should persist. It further discloses side effects the annotations cannot express — answers and picked teams survive if kick-off is unchanged, but are reset and the squad is notified if it moves.

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 core action and permission constraint are front-loaded in the first sentence, followed by replace semantics and side effects. It is dense but every sentence carries information; only the parenthetical default list is slightly list-heavy.

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 mutation with no output schema, the description covers destruction semantics, side effects, and redirects to get_squad for reading state. It stops short of stating what set_game itself returns, which is a minor gap given get_squad is offered as the inspection path.

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 all seven parameters, making 3 the baseline. The description adds meaningful semantics the schema does not: the replace-on-omission behavior ('anything left out goes back to its default, so pass what should stay'), which changes how an agent must populate the optional fields.

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

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

The description states a specific verb and resource ('Set when and where a squad plays'), adds a scope qualifier ('organisers only'), and distinguishes itself from the read-side sibling by pointing to get_squad for the current game. An agent can tell it apart from create_squad or answer_game without opening any schema.

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

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

It gives clear context for when to use it (setting/changing a squad's kick-off and venue, restricted to organisers) and names get_squad as the way to inspect current state before/after. It lacks explicit 'when not to use' or comparison to alternatives like create_squad, 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?

Annotations already declare this a read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuinely useful behavioral detail not in the annotations: the fixed output count of ten and the default behavior when no arguments are supplied. It says nothing about determinism, duplicates, or regeneration across calls.

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

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

Two compact sentences, front-loaded with the action and resource, then the mode distinctions and the default. Every clause carries information; no filler or repetition of the title.

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

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

For a zero-required-parameter, read-only generator with no output schema, the description supplies exactly what's needed: what gets generated, in what quantity, and under which input combination. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, and the enum values are each documented inline in the schema, so the schema carries parameter meaning. The description restates the theme/word modes and notes the neither-case default but adds no new format or constraint detail beyond the schema's own precedence note.

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) and enumerates the two generation modes plus the fallback. An agent can immediately tell this apart from siblings like make_fair_teams or create_squad, which operate on existing teams.

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?

Explains the input conditions that select each mode: pass a theme for themed randomness, a word for club-style names, or neither for all themes. It does not explicitly rule out or point to any sibling tool, but the sibling set is clearly about teams/fixtures rather than name ideation, so the routing context is unambiguous.

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