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

With no annotations, the description carries the full burden, but it does disclose the key behavior: the round ends, the move can be countered, and the caller may bear a covering penalty (包牌惩罚). It does not state whether the action is reversible, what happens to a successful vs. countered call, or any permission/precondition rules.

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 compact sentence that front-loads the action and its effect. Nothing is wasted, though a reader unfamiliar with the game's terminology gets no elaboration.

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 mutating round-ending game action with no annotations and no output schema, the description covers the gist and the main risk, but leaves out the success outcome, scoring implications, and failure modes beyond stale revisions.

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 revision parameter is already fully explained (latest-state revision; stale operations rejected) in the schema. The description adds nothing about parameters, 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?

Names a specific action (发起算牌, initiate the calc declaration) and its immediate effect (结束本轮, ends the current round). It also gestures at the counter-mechanic ('可能被反算'), which loosely relates it to the respond_anti_calc sibling, but it never names alternatives explicitly.

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 statement of when to call this rather than play_cards, discard_card, or wait_for_action. Only consequences ('may be countered') are given, which is context for the decision, not guidance on making it.

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

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

With no annotations, the description carries the full burden and does add one real behavioral fact: after the discard, other players may choose to play in (插牌), which affects game flow. However, it says nothing about whether this is irreversible, whether it consumes the turn, what permissions or game state are required, or what happens to the discarded card beyond the immediate action.

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 tight sentence with no filler, front-loading the core action and then the follow-up consequence. It is efficient, though it leaves the action without any surrounding context that would help an agent place it in the turn flow.

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 state-mutating game action with no annotations, no output schema, and a nested required parameter, the description is only partially sufficient. It discloses the reaction phase, but omits turn prerequisites, the meaning of the card's color field, and any indication of the result, which the missing annotations and output schema leave uncovered.

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 only 50%: revision is documented in the schema, but the nested card object has no field descriptions, and the description says only '一张牌' without explaining that it is an id+color pair or what the color integers 0-3 mean. The enum on id and range on color give structural constraints but no semantic meaning, and the description does not compensate.

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: discard one card from your own hand, plus the follow-up where other players decide whether to play in (插牌). That is clear enough to act on, but it never distinguishes this action from siblings like play_cards, select_cards, or draw_card, leaving the agent to infer which card-moving tool to pick.

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 statement of when this tool applies versus alternatives, no turn or game-phase prerequisite, and no pointer to play_cards/draw_card as siblings. The only contextual information is the post-discard reaction phase, which describes consequence rather than selection guidance.

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

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

With no annotations, the description carries the full burden. It does disclose a meaningful state transition (entering the discard phase after drawing), which is real value beyond the schema. It says nothing about failure modes (stale revision rejection is only in the schema), hand-size limits, or what the tool returns.

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 tightly written sentence with the action front-loaded and the consequence trailing. Nothing is wasted, though the extreme brevity leaves gaps that could have been filled cheaply.

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 game action with a fully documented schema and no output schema, the description covers the core action and its follow-on phase. It stops short of stating turn/phase preconditions or error behavior, which an agent needs to invoke this reliably without trial and error.

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% — the single 'revision' parameter is documented as 'latest state revision; stale operations are rejected.' The description adds no parameter context, but the schema already does the work, so 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 (draw a card) that is distinguishable from sibling actions like play_cards, select_cards and discard_card. It does not explicitly name those siblings or clarify the boundary, but the action 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?

The clause '之后进入弃牌阶段' implies the tool belongs to a draw step followed by a discard step, which weakly points the agent toward discard_card next. There is no explicit when-to-use/when-not guidance, prerequisites, or named alternatives.

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

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

Consistent with readOnlyHint=true and adds real context beyond annotations: only the cached 100 messages are visible, earlier records may be lost when truncated is set, and from/msg must be treated as untrusted player input. It doesn't cover things like refresh behavior or ordering guarantees, but for a cached read it is substantive.

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 clauses, front-loaded with what is read and how much. Every sentence carries distinct information: scope, pagination, truncation, and data trust.

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?

No output schema exists, and the description compensates by naming the latestId and truncated return fields and warning about untrusted from/msg content. It still leaves the shape of the message list and the origin of from unspecified.

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 0%, so the description must carry the load, and it does: afterId is defined as the incremental read anchor and latestId is named as the value to feed into the next call. The integer default of 0 and the bounds remain documented only in the schema.

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

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

States a specific verb (读取/read) and resource (聊天/chat messages) with explicit scope: the most recent 100 messages cached in the current connection. This clearly separates it from the sibling send_chat, which writes, while this only reads cached data.

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 that afterId is for incremental reading, which tells the agent when to pass it rather than the default 0. It does not give an explicit 'when not to use' rule or name an alternative read path, so it falls short of a full 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?

readOnlyHint=true already covers the safety profile, so the description's contribution is the visibility boundary: it states opponent hands and the deck are NOT exposed, and that the data is cached. That is genuine added context an agent needs to interpret results and avoid attempting to read hidden information.

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 with zero waste: first enumerates what is returned, second states the exclusion. Front-loaded with the resource and the most decision-relevant item (available actions).

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 effectively substitutes for one by listing the returned fields — hand, public info, pending choices, actions — plus the explicit non-returned fields. For a zero-param cached-state read tool, an agent has everything needed to call and interpret it.

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 there is nothing to disambiguate; the schema and description are consistent. Baseline applies, and the description instead spends its words on the return payload, which is the more useful investment here.

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 (读取) plus a concrete enumerated resource set: cached table state, own hand, public info, pending choices, available actions. An agent immediately knows what it gets. It does not explicitly contrast with any sibling tool, which keeps it at 4 rather than 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?

Usage is implied — the mention of '当前可用动作' (currently available actions) signals this is the read-before-act tool that feeds the many action siblings (play_cards, draw_card, respond_cha, etc.), but the description never states when to call it or that it should precede an action.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the join/spectate timing behavior and that a playerId is returned for reconnection, but it does not cover edge cases such as room-full, invalid room, or authentication requirements.

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

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

The description is three short clauses with no waste. The core action is front-loaded, followed by the critical timing constraint and return value.

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

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

For a four-parameter join tool with no output schema, the description covers the essential purpose, timing rule, and returned playerId. It is mostly complete, though it could mention error or room-availability behavior.

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 50%, with url and playerId documented in the schema. The description adds meaning for playerId by explaining it is returned for reconnection, but it does not clarify the room or name parameters, leaving half the parameters without added semantic guidance.

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: connect/join the 250 game as an ordinary player. It also clarifies the timing constraint and the returned playerId, making the core action immediately understandable.

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 timing guidance: join before the game starts; after the start, new IDs can only spectate. This clearly frames when this tool is appropriate, though it does not name an alternative tool for late-joining players.

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

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

With no annotations, the description carries the full burden and does add real behavioral context: mid-game exit triggers server-side trusteeship, and reconnection with the original playerId is possible. Missing only minor details such as whether the session is fully terminated or what the response contains.

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 with zero waste, the core action front-loaded before the side-effect and recovery note.

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 zero parameters, no annotations, and no output schema, the description covers the essentials an agent needs: what happens on mid-game exit and how to recover. Return behavior for a simple disconnect is the only remaining gap, and it is minor.

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 and the description correctly adds no parameter detail. However, it references 'playerId' for reconnection without clarifying that this is not an input to this tool, which is a small potential ambiguity.

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: closing the game connection. It is clearly distinct from sibling tools like join_game or wait_for_action, though it never names an alternative explicitly, so the differentiation is inferred rather than stated.

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 consequence of invoking it while a game is in progress (server-side auto-play) and offers a recovery path via the original playerId. That is clear usage context, but it doesn't state when not to use it or point to an alternative 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?

With no annotations, the description carries the full burden. It discloses two useful traits: local checking against server same-version rules (so operations may be rejected) and the possibility of returning a 'pending' state requiring further selection. It omits whether the move commits permanently, what happens to the chosen cards, and how a rejection surfaces, leaving key behavior unstated for a mutation tool.

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 clauses, front-loaded with the action and followed by behavior notes; there is no filler. Slightly more content would have been worthwhile, but nothing written is wasted.

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 3-parameter mutation tool with no annotations and no output schema, the description does supply the important 'may return pending' return behavior and the validation model. It still lacks the semantics of putMethod, card/color encoding, and error/commit behavior, which an agent would need to call this correctly rather than by trial and error.

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 only 33%: revision is documented in the schema, but 'cards' (id enum, color 0-3) and 'putMethod' (1 or 2) have no explanation in either place. The phrase '摆牌或补牌' loosely maps to the two putMethod modes but never states that mapping, and the card/color encoding is left entirely unexplained, so the description does not compensate for the coverage gap.

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

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

The description names two actions (playing cards from hand and replenishing/drawing) and hints at a pending follow-up state. However, it does not distinguish the tool from close siblings like select_cards, draw_card, and discard_card, which appear to cover overlapping ground, so an agent cannot tell from the text alone which of these to pick.

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 statement of when to use this versus the alternatives (select_cards, draw_card, discard_card, select_put_method), nor prerequisites such as turn ownership or required prior state. Usage is only implied by the phrase 'from hand or replenish'.

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?

No annotations are provided, so the description must carry behavioral context. It usefully discloses that the tool returns 'sent' and then waits for results, and that false means abandoning the phase, but it omits error handling, permission requirements, and the consequences of abandoning.

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

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

The description is two short clauses, front-loaded with the action and then the boolean semantics plus return/wait behavior. It contains no filler and every part adds useful 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 simple two-parameter phase response with no output schema, the description covers the core action, both boolean branches, and that it returns 'sent' before waiting. It still leaves open what result arrives after waiting and what abandoning implies, so it is adequate but not fully complete.

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

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

Schema coverage is 50%: revision is documented in the schema, while participate has no schema description. The description compensates by defining participate=false as abandon and true as participate, adding meaning beyond the bare boolean type.

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

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

The description states the specific action: responding during the anti-calculation phase, and defines both boolean branches (participate=false abandons, true participates). This makes the tool distinguishable from generic chat/card siblings, though it does not explicitly name alternatives like respond_cha.

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 identifies the relevant phase ('反算阶段') and explains how the required participate parameter selects between abandoning and participating. It lacks explicit when-not or alternative-tool guidance, but the usage context is clear.

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

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

With no annotations, the description carries the full burden. It usefully discloses that cards must contain only your own hand (not the discard pile) and that you must not resubmit after returning 'sent' — a valuable idempotency warning. It omits what happens on revision mismatch or failure handling, leaving gaps for a mutation tool.

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 dense clauses with no filler, and the phase context is front-loaded. Every sentence adds actionable information; it could be marginally clearer about the 'cards' payload but wastes nothing.

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 game-phase responder with no output schema, the description covers the key things an agent needs: the phase, the participate branch, the cards payload restriction, and the submit-once wait behavior. Only failure/return details are slightly thin, which is acceptable given there is no output schema.

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

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

Schema coverage is only 33%, but the description compensates: it defines participate's semantics (false=forfeit, true=submit) and constrains cards to own hand only, excluding discards. revision is documented in the schema itself, so all three parameters gain meaning.

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

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

The description states '响应插牌阶段' (respond to the insert-card phase), giving a verb tied to a specific game phase, which distinguishes it from siblings like play_cards or respond_anti_calc. However, '插牌阶段' is unexplained game jargon, so an agent unfamiliar with the rules cannot fully grasp what action is being performed.

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 explains the participate=false (forfeit) vs true (submit cards) branches, which is contextual usage guidance. But it never explicitly says when to choose this tool over siblings like respond_anti_calc or play_cards; the phase is only implied by the tool name.

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

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

With no annotations, the description carries the full behavioral burden. It states the trigger and the exact-count/distinct-card constraint, but does not disclose that this mutates game state, whether the selection is final, what happens on invalid choices, or any turn/error consequences.

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

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

The description is a single front-loaded sentence with no wasted text. Its terseness is more a completeness issue than a conciseness issue, but the undefined terms make the sentence slightly opaque.

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 game-state-mutating action with no output schema and no annotations, the description is thin. It does not explain where 'options' and 'count' come from, how card objects are formed, or what the result/state change will be.

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 50%, so the description should compensate. It adds 'exactly count distinct' semantics, but references 'options' and 'count' that are not parameters, and gives no explanation of the cards array structure or the required revision beyond what the schema already 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?

The description states a specific verb and resource ('select ... cards') and ties the action to a concrete game phase ('pending.kind=cards'). It is distinguishable from siblings like play_cards or draw_card, though 'count' and 'options' are undefined external state references.

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 clearly says to use this tool when responding to pending.kind=cards, which is a strong usage trigger. It does not mention exclusions or alternatives, but the phase condition gives practical 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?

No annotations are provided, so the description carries the full behavioral burden. It explains the value mapping but does not say what happens after selection, whether the choice is final, what validation applies beyond the schema's revision note, or what game/turn consequences follow.

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

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

The description is a single compact sentence that front-loads the trigger condition and then gives the value mapping. There is no wasted text, and the structure makes the key mapping easy to scan.

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

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

For a two-parameter selection tool with no annotations or output schema, the description gives enough to identify the trigger and the value choices. However, it leaves out behavioral details an agent would need to invoke it confidently, such as the effect or finality of the selection and any consequences beyond the revision check.

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 50%, with only `revision` documented in the schema. The description compensates by explaining the otherwise opaque `value` constants: `1` means straight and `2` means same-point array, adding real semantic value beyond the schema's `const` values.

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 trigger (`pending.kind=putMethod`) and maps the selectable values (`1` straight, `2` same-point array), so the action is identifiable. It does not fully explain what a `putMethod` selection means in game terms, but it is more specific than the tool name alone.

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 condition for use is explicit: respond when `pending.kind=putMethod`. It does not name alternatives or exclusion cases versus sibling tools such as `play_cards` or `select_cards`, but the trigger context is clear.

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

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

With no annotations, the description carries the burden and does well: it discloses the identity used for the sender, the permission model (players and spectators), that no revision/locking is needed, and that 'sent' is fire-and-forget with no delivery guarantee. Missing only rate limits or whether the sender is echoed the message.

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 carrying distinct information, with the core action front-loaded. Nothing 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?

For a one-parameter, no-output-schema tool, the description covers identity, permissions, revision requirements, and the return-value caveat. Room visibility/ordering of delivered messages would be the only remaining detail an agent might want.

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 0% for a single required 'message' parameter, so the description would ideally say something about content. It says nothing about the message body, though the schema's minLength 1 / maxLength 2000 constraints make the parameter self-evident, so the gap is minor.

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 (send chat) scoped to the current room, and immediately clarifies the identity source (the name used when joining). It is unmistakably distinct from the read-side sibling get_chat_messages.

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 both players and spectators may send and that no revision token is required, which pre-empts the main confusion versus the other game actions (play_cards, discard_card) that do require revisions. It stops short of naming a sibling alternative or stating when not to use it, but the context is clear.

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

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

No annotations are provided, so the description carries the burden, and it does well: partial-update semantics (omitted fields preserved), empty-string clears the avatar, the backend only persists profile.name and does not alter the display name, and stale revisions are rejected. This is substantial behavioral context beyond the schema.

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

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

Front-loads the purpose, then layers constraints. It is dense but each clause (avatar semantics, name caveat, player-only, revision) earns its place with little redundancy.

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

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

Given a 2-param nested-object mutation with no annotations and no output schema, the description covers side effects, partial-update rules, permissions, and concurrency. Nothing essential to calling it correctly appears to be missing.

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

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

Schema coverage is only 50%, but the description compensates: it defines profile.back as an HTTP(S) image URL and documents empty-string/omitted behavior, and explains that profile.name is saved without changing the displayed name. Both nested params gain meaning the schema alone lacks.

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 ('修改自己的角色资料') and immediately scopes what 'profile.back' represents. It also distinguishes itself from join_game by clarifying that display names are set via join_game.name, not here, which lets an agent route correctly among 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 clear preconditions ('仅玩家可用', '需最新 revision') and an explicit alternative for a related task (use join_game.name to set names). It stops short of enumerating when NOT to call it (e.g., spectator contexts beyond 'player only'), but the context is strong.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does surface the most important trait — that the last ready vote triggers an immediate game start or next round, a significant side effect — but says nothing about whether you must already be in a game, whether the toggle is idempotent, or how failures present (the stale-revision rejection is documented only in the schema).

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

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

Two short sentences, zero filler, and the core action is front-loaded ahead of the consequence and the precondition. Every clause adds information an agent would otherwise have to guess.

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 toggle with no output schema, the description covers purpose, the critical downstream effect, and a prerequisite. The only real gap is error/eligibility behavior (e.g. calling outside a lobby), which is not covered by annotations either.

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 50%: `revision` is documented in the schema, while the `ready` boolean (default true) is not. The phrase '准备或取消准备' does implicitly convey that the boolean toggles ready on/off, which partly compensates, but the default value and the meaning of omitting the field are left to the schema.

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

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

The description names a concrete verb pair (ready / cancel-ready) on the player's own ready state, which is distinct from every sibling tool (play_cards, join_game, get_state, etc.). It is clear what the tool does, though it never names the boolean parameter that performs the toggle.

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 the operative context — when all players are ready the game starts immediately or advances to the next round — and gives a precondition (confirm players have joined/are present), which implicitly routes the agent to join_game first. There is no explicit when-not guidance, but there is no competing 'ready' alternative in the sibling list.

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, so the safety profile is covered. The description adds useful operational context: it blocks until a revision change or timeout, returns the latest state, and waiting can continue after a timeout.

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 compact sentences with the core wait-and-return behavior front-loaded. There is little waste, though the insert-card/anti-calculation clause is slightly context-dependent.

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

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

For a read-only wait tool with no output schema, the description covers the trigger, returned value, and post-timeout behavior. It is less complete on timeoutMs semantics, but the schema supplies default and maximum values.

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

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

Schema coverage is only 50%: afterRevision is documented in the schema, but timeoutMs has no schema description. The tool description references revision indirectly but gives no semantics for timeoutMs, such as its default or maximum, so it does not compensate for the gap.

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

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

States a specific verb (wait) and trigger (revision update or timeout), plus the return value (latest state). The clause about insert-card and anti-calculation responses clarifies it is not only for the player's own turn, though it does not name sibling tools 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?

Explains that the tool waits for a revision update or timeout and that it is relevant beyond one's own turn, including when other actions need responses. However, it does not name alternatives such as get_state or clearly specify when not to use it.

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