Beleeg

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

Adds substantial behavior beyond the annotations: the change becomes permanently unconfirmable, only the preparer may cancel it, and calling it on an already-confirmed change reports that fact rather than undoing it. The annotations cover the safety profile (destructiveHint=false, idempotentHint=true) and the description adds authorization and state-transition semantics 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?

Purpose is front-loaded, then usage triggers, then the non-undo boundary, then id lookup and permissions. Each sentence carries distinct information, though the permission clause could have been folded into the boundary sentence.

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

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

An output schema exists, so return values need no explanation, and the description already states what happens on a confirmed change. Auth requirement, id acquisition, and irreversibility of the cancel are all present, leaving no gap for a single-param 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 100%, so the schema already defines prepare_id as a UUID. The description adds the operational route for obtaining that value ('Find the prepare_id with beleeg_look_up(what: "my_changes")'), which is meaning the schema cannot carry.

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 ('Drop') and resource ('a change that was prepared but never confirmed'), and explicitly contrasts with beleeg_confirm_change by defining the window in which the change exists. An agent can distinguish this from confirm/look_up siblings 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?

Gives concrete trigger phrases ('no', 'cancel that', 'never mind'), names the alternative path for already-confirmed changes ('the reverse has to be asked for as a new change'), and explains how to obtain the required id via beleeg_look_up. Both when-to-use and when-not are covered.

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 destructive/idempotent/openWorld, but the description adds materially new behavior: the prepare_id is single-use, bound to the same person, valid for 10 minutes, and re-confirmation returns already_done:true rather than re-applying. It also discloses side effects (email/payment delivery, checkout_url), audit logging, and the required token scope.

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-loads 'CONFIRM' and the core rule, then layers constraints and side effects. It is on the longer side, but each sentence carries operational information and none 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 destructive, state-changing tool this covers preconditions, idempotency behavior, side effects, and auth needs. With an output schema present, it correctly avoids over-explaining return shape while still noting the already_done field and checkout_url.

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 parameter is documented there, so baseline is 3; however the description adds lifecycle semantics for prepare_id (single use, same person, 10-minute window) that the schema does not convey.

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

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

Opens with a specific verb and immediately states the consequence ('this is the step that actually makes the change'), cleanly separating it from beleeg_prepare_change. An agent can identify the tool's role without inspecting 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 explicit when-to-use rules: only with a prepare_id from beleeg_prepare_change, only after showing the summary and receiving a 'yes', and never on the agent's own initiative. This is about as prescriptive as guidance gets.

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 read-only, idempotent, and non-destructive, but the description adds important behavioral context: answers should be relayed as written, times already include their time zone, and several operations are restricted to league admins, team members, or platform admins. This goes well beyond the structured safety 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 long, but the length is justified by 45 distinct operations and the absence of an output schema. It is front-loaded with global selection guidance, then uses a compact bulleted structure where each entry earns its place by naming the resource, params, and returned 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?

Given the 22 parameters, the 45-value enum, no output schema, and the multiplexed design, the description is complete: it covers routing alternatives, permission scopes, parameter mapping, pagination hints via `limit`/`cursor`, and return content for every `what` value.

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 already 100%, yet the description still adds substantial value by grouping each `what` value with its valid parameters and optionality, and by describing what each operation returns. That operation-level mapping is more useful than the per-parameter schema alone for a 22-param multiplexer.

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 read-only lookup role in the person's Beleeg leagues and enumerates every supported resource via the `what` values. It explicitly distinguishes itself from siblings `beleeg_needs_me` and `beleeg_look_up_public`, so an agent can route correctly without opening schemas.

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

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

It gives explicit selection guidance: pick `what`, pass only the listed params, get `league_id` from `beleeg_whoami`, and use `beleeg_needs_me` or `beleeg_look_up_public` instead when those conditions apply. Each `what` entry also states admin-only or team-only restrictions where relevant.

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 (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower; the description reinforces 'Read-only' and adds genuinely new context about the public/no-membership access boundary. It also discloses what each lookup returns (roster, captain, colours, recent matches; status, entrants, bracket), which is real behavioral detail. It does not cover pagination or result limits.

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 statement of purpose and access scope, followed by a scannable per-value parameter list where every line maps a branch to its input and output summary. Tight and well organized; only mildly verbose in restating the title's notion of a 'public page' twice.

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 fields returned for each lookup type, and it fully documents which parameter goes with which branch. Combined with 100% schema coverage and strong annotations, an agent has what it needs. The only soft spot is the schema's references to nonexistent 'schedule'/'tournaments' enum values, which the description never addresses.

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

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

Schema coverage is 100%, so baseline is 3; the description goes beyond it by mapping each `what` enum value to the exact parameter it consumes and summarizing the returned fields per type. It does not clarify the schema's dangling references ('from what "schedule"' / 'from what "tournaments"') to enum values that do not exist in the list, which is a real ambiguity left unresolved.

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 (look up) plus the exact resource class (league, team, match, tournament public pages) and pins the distinguishing constraint: 'no membership needed. Read-only.' This separates it from the sibling beleeg_look_up, which an agent can infer is the authenticated counterpart, 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?

It states when to use this tool (public content viewable by anyone) and enumerates, per `what` value, exactly which param to supply: slug, match_id, tournament_id, league_slug. That is usable routing guidance. It stops short of an explicit exclusion such as 'do not use for private/authenticated data — use beleeg_look_up', which is only implied by 'no membership needed'.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is settled. The description adds genuine behavioral context beyond that: it is cross-league, organizer-scoped only, each item is tagged with its league and links to the relevant page, and it explicitly performs no mutation. It does not discuss pagination or result size, which is the only remaining 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?

Front-loaded with the core claim, then the item enumeration, then scope exclusions and the routing sentence. The long item list is dense but each entry adds discriminating detail; the weak spot is that the enumeration could be tightened slightly without losing meaning.

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

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

An output schema exists, so return values need not be spelled out, and the description still previews what each item contains (league tag plus link). For a no-arg, read-only aggregator this covers everything an agent needs to select and invoke it correctly, including the sibling it should call afterwards.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline is 4. The description correctly conveys that the call needs no input ('in one call') and does not waste space restating a schema that is empty.

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+scope: everything waiting on the person, across every league they run, with an explicit enumeration of item types (unscored matches, unconfirmed reports, disputes, unsent lineups, unpaid members, closing registration, missing settings). An agent can distinguish this aggregate 'inbox' tool from beleeg_prepare_change, beleeg_look_up and the other siblings 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?

Gives concrete triggering questions ('what needs me this week?', 'am I behind on anything?'), states an explicit exclusion ('Leagues the person only plays in are left out'), and routes to the alternative: 'Nothing here is a change; use it to decide which change to prepare next.' When-to-use, when-not, and the follow-up tool are all present.

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 non-read-only/non-destructive/idempotent, and the description reinforces and extends them: prepare_id TTL ('works for 10 minutes'), the auth requirement ('Needs a token that allows changes'), the out-of-band Approve step for some actions, and explicit error behavior ('the reply lists exactly what the action takes'). None of that is in 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?

Very long, but the length is largely earned: it is a 46-action dispatcher whose params are documented nowhere else, and it is front-loaded with the PREPARE-ONLY constraint and the confirm workflow before the catalog. A few per-action blurbs drift into edge-case prose, so it is not maximally tight, but there is little pure 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 complex dispatcher with an output schema, the description covers everything an agent needs to call it correctly: the prepare/confirm contract, TTL, auth, approval fallbacks, time-zone rules, id sources, and per-action param shapes. Return values are handled by the output schema and are not redundantly re-explained.

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 is a generic dispatcher (action enum + free-form params object), so the description carries the entire parameter burden and does so exhaustively, listing every action's params, optionality, types, and per-field semantics (e.g. newTime is league-local, never UTC; leave it out to keep the same time). This adds far more than the schema provides.

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

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

Opens with a specific, unambiguous verb+resource+scope: 'PREPARE ONLY — nothing changes yet. Pick the change (action) and give its params.' It distinguishes itself from the sibling that actually commits the change by name (beleeg_confirm_change) and states exactly what it produces (a summary plus a prepare_id). An agent can tell this apart from confirm/cancel 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?

Explicit when/when-not and sequencing: 'call beleeg_confirm_change with the prepare_id only after they agree', plus the additional approval condition for sensitive actions (league-wide email, money record). It also names the sibling tools that supply required ids (beleeg_whoami for league ids, beleeg_look_up for match ids), which is real 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 already declare idempotentHint=true and destructiveHint=false, and the description reinforces and extends this with a concrete safety guarantee ('nobody can be emailed twice for the same request'), a bounded retry policy (gives up after three attempts), a fallback path, and an auth requirement ('needs a token that allows changes'). This is substantial 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?

Front-loaded with the core action, then usage trigger, safety, retry limits, and auth needs. Six sentences is slightly long, but each carries distinct information and none is redundant with annotations or schema.

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 an output schema exists and annotations cover the safety profile, the description fills the remaining gaps: trigger conditions, retry ceiling, fallback behavior, and permission requirement. An agent has everything needed 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 100% for the single prepare_id parameter, and the schema already explains it is the prepare_id whose email or payment step needs another attempt. The description adds no syntax or format detail beyond what the schema provides, 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?

The description states a specific verb ('try the sending step again') and a precise resource scope ('a change that was already made but whose emails or payment link did not finish going out'), and explicitly differentiates from the change itself ('does NOT redo the change itself, only the sending'). An agent can distinguish this from beleeg_confirm_change and beleeg_prepare_change immediately.

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 names the exact trigger condition: use it when a confirm or beleeg_look_up(what: "my_changes") reports delivery_failed or delivery_unknown. It also gives a when-not (don't use it to redo the change) and states the alternative fallback (send from the Beleeg site after three failures).

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 this is a non-read, non-idempotent, non-destructive write. The description adds meaningful behavior beyond that: the Beleeg team reads submissions to prioritize work, nothing happens automatically, no one replies, and personal details (names, emails, phone numbers) must never be included. It does not mention any rate limits or what the call returns, but the privacy prohibition and no-reply semantics are substantive 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?

The trigger condition is front-loaded in the first sentence and each subsequent sentence carries a distinct constraint (attribution, privacy, no-reply escalation back to the user). The final sentence is long and packs three ideas, but none of it is filler for a tool with this much policy attached.

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

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

An output schema exists, so return values need no explanation, and the description covers triggers, required content, privacy rules, and the expectation of no follow-up. The three parameters are all documented in-schema. What remains thin is what happens after submission beyond 'the team reads these,' but that is minor for a fire-and-forget feedback tool.

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

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

Schema description coverage is 100% and each parameter already carries a description and example (e.g. trying_to's "move all of Saturday's games to Sunday"). The description's 'Say what they wanted and, if one did, which tool fell short' essentially restates the schema fields at a high level, adding intent framing but no new format or constraint 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?

The description states a specific verb and resource ('Send Beleeg a note') and defines the exact triggering conditions: the assistant cannot do something the person asked for, a tool was confusing, or a wrong answer was given. Siblings (look up, start league, start tournament) are functionally unrelated, so no disambiguation is needed and none is missed.

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 explicit when-to-use conditions and an important counter-instruction: because nothing is done automatically and nobody replies, the agent must still tell the person what could not be done and, where possible, point them to where in Beleeg they can do it themselves. This is exactly the routing decision an agent needs and is not inferable elsewhere.

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 cover the safety profile (readOnly=false, openWorld=false, idempotent=false, destructive=false). The description adds substantial behavioral context the annotations cannot convey: the claim_url/is-it-theirs ownership flow, that sign-in alone does not transfer ownership, that invites stay unsent until the organizer keeps the league, the 30-day removal, and concrete rate limits (3/organizer/day, 5/caller/day, 3 pending).

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 purpose and claim mechanics, and almost every sentence carries operational value (claim_url handling, limits, dedup rule, confirmation requirement). Slight redundancy: ownership is restated ('Signing in alone does not make it theirs' vs 'it is theirs only once they keep it'), and the keep/discard flow is mentioned twice.

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 an output schema exists, return-value detail is not required, and the description still covers the full operational picture: creation side effects, ownership/claim flow, invite deferral, expiry, rate limits, and the mandatory confirmation step. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all ten parameters are already documented in the schema, setting the baseline at 3. The description reinforces a few constraints (organizer email must be asked for and never guessed, team-name capitalization/spacing normalization) but adds little parameter detail beyond what the schema already states.

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 ('Creates a real league on Beleeg right away') with a clear scope qualifier: for someone without a Beleeg account. This cleanly separates it from the sibling prepare_create_league / prepare_* family, which only stage actions.

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 when-to-use ('someone who does not have a Beleeg account yet'), prerequisites (ask for the email, never guess), and a required pre-call step ('Tell the person what you are about to create and get a yes BEFORE calling this; there is no separate confirm step'), plus fallback behavior when Beleeg refuses.

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 annotations, the description discloses important behavior: the bracket is held for the organizer until they claim it, signing in alone is insufficient, nobody else can see entrants until it is kept, and unclaimed brackets are removed after 30 days. It also states concrete limits: up to 64 entrants (32 for round robin), 3 per organizer email per day, 5 per caller per day, and at most 3 waiting leagues or brackets. It does not contradict the annotations.

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

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

The description is long but front-loaded: it states the core action first, then the claim process, visibility rules, retention, limits, and pre-call confirmation. Every sentence carries operational information needed to avoid mistakes, and there is no redundant filler. The density is justified by the complexity of the 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?

Given the tool's complexity and the existence of an output schema, the description covers the missing behavioral context thoroughly: accountless creation, claim flow, visibility, retention, rate limits, and confirmation requirements. It does not need to explain return values because an output schema is present. An agent has enough information to invoke the tool correctly and guide the user afterward.

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 seven parameters, including entrants, format, bestOf, and organizerEmail. The description reinforces a few constraints, such as entrant limits and pair naming, but adds no parameter syntax or meaning beyond what the schema provides. With full schema coverage, 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 opens with a specific verb and resource: 'Creates a real standalone tournament bracket on Beleeg.' It immediately distinguishes the tool from a league-creation sibling by stating the bracket 'is never attached to an existing league or organization.' It also clarifies the no-account use case, so an agent can tell what this tool does 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?

The description clearly defines the usage context: for someone without a Beleeg account, creating a standalone bracket rather than one attached to a league or organization. It also gives workflow guidance such as asking for the organizer's email, never guessing it, and getting a yes before calling. However, it does not explicitly name an alternative sibling tool such as beleeg_start_league, so it stops short of the full when-to-use-vs-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, idempotentHint, and destructiveHint=false, so safety is covered; the description adds real value by disclosing the return payload (identity, leagues, roles, time zones, per-league permission plus plain-word reason) and the token's overall write capability. It stops short of format/shape details, which the output schema presumably carries.

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 actionable 'START HERE' imperative and the payload contents, then closes with the alternative routing. It runs a bit long and lists its returns in an embedded clause, but every sentence carries distinct 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 an output schema exists, the description need not explain the return shape, yet it still summarizes what comes back and what the permission fields mean. Combined with annotations covering the read-only profile, an agent has everything needed to call it correctly first.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for no-params tools applies. The only parameter-like detail is the cross-reference to beleeg_look_up(what: "search_leagues"), which aids routing rather than this tool's inputs.

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 ('tells you who this connection belongs to') with enumerated scope: leagues, league_id, roles, time zones, and change permission with reasons. An agent can immediately distinguish this identity/permission bootstrap from siblings like beleeg_look_up or beleeg_needs_me.

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 says 'START HERE in a new conversation' and gives the discover-by-refusal anti-pattern it replaces. It also names the exact alternative and condition for a different case: 'For a league the person is NOT in, use beleeg_look_up(what: "search_leagues")'.

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