chesswithclaw

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

No annotations are provided, so the description carries the full burden. It describes a creation action but does not disclose side effects, prerequisites, whether the game is immediately joinable, or what the agent receives in response. The statement about not waiting is more of a usage directive than a behavioral disclosure.

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, focused sentence that front-loads the purpose and provides key usage guidance. Every part adds value, and no unnecessary words are used.

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 one parameter and no output schema, the description still needs to explain the parameter and expected behavior, but it does neither. The tool is simple, yet the description leaves significant gaps about what happens after creation and what 'agent_name' is for.

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

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

The input schema has one parameter 'agent_name' with no description and 0% schema coverage. The tool description does not mention this parameter at all, leaving the agent without any guidance on what value to provide or its purpose.

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

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

The description clearly states the tool creates a brand new ChessWithClaw game, using the specific verb 'set up' and a resource. It also differentiates from the sibling join_game by emphasizing the agent can act on its own initiative without waiting for an invitation.

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

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

The description explicitly indicates when to use the tool: when the agent wants to start a game on its own initiative, without needing the human to start it or waiting for an invitation. It implicitly contrasts with join_game, providing clear usage context, though it does not name the sibling tool directly.

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 transparency burden. The verb 'Fetch' suggests a read-only operation, and the content is informational, but the description does not explicitly state side effects or the nature of the returned data.

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, focused sentence of about 15 words. It front-loads the verb and resource, contains no filler, and every word contributes to the tool's 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?

For a zero-parameter tool, the description conveys the conceptual content of the guide and when it might be relevant. However, without an output schema, it leaves the return format unstated, which may leave an agent unsure what to expect.

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

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

The input schema has zero parameters and schema coverage is trivially 100%. With no parameters to document, the description need not add parameter semantics; the baseline score of 4 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 clearly identifies the action ('Fetch') and resource ('companion guide principles'), and specifies the guiding purpose ('thinking about chess positions and being genuinely present'). This distinguishes it from sibling tools focused on game actions like move creation or state queries.

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 intended use is implied by the tool name and description: use it when you need the companion guide. However, there is no explicit when-to-use or when-not-to-use guidance, nor references to alternative tools.

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 provided, the description carries the full burden of behavioral disclosure. It communicates that this is a read-only observation operation by saying to 'look at the board' and explicitly states there is no penalty for frequent calls. It does not go into rate limits or side effects, but the no-penalty detail is meaningful and compensates for the absence of 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 two sentences long, front-loads the most important information, and every clause earns its place. The first sentence lists what is returned, and the second gives usage context and cost guidance. There is no redundancy or filler.

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

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

The description does a good job of explaining what the tool returns despite lacking an output schema, naming FEN, ASCII board, move history, chat, clock, presence, and timestamps. It also covers the cost/usage context. The main gap is that it does not clarify how optional parameters control the response or what identifiers are required, so it is 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 description coverage is only 50%, and the description does not address the game_id or agent_token parameters at all. It also does not explain how chat_limit or since_message_id affect the returned chat history, even though those are the only parameters with schema descriptions. The description adds no semantic value beyond the input schema.

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

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

The description opens with a specific verb and resource: fetching the full game state as visible to the human. It clearly enumerates the state contents (FEN, board, move history, chat, clock, presence, timestamps), which differentiates it from siblings like get_legal_moves. An agent can immediately tell what this tool is for.

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

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

The description provides an explicit trigger condition: call this whenever you want to look at the board. It also reassures there is no penalty for checking often, which is highly actionable guidance. It does not mention when not to use it or name alternatives, so it stops short of a perfect score.

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 explains that the tool computes only rules-based moves, not evaluations, and describes the behavior of omitting `square` to get all legal moves. It stops short of explicitly stating it is read-only or has no side effects, but the 'pure rules' framing strongly implies a non-mutating operation.

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

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

The description is appropriately sized with three sentences, each serving a purpose: defining the tool, clarifying what it is not, and explaining the optional parameter. The phrase 'not an opinion about what is good' is slightly redundant but contributes to the overall clarity. Overall it is well-structured and front-loaded with the core concept.

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

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

Given the tool's simplicity and lack of output schema, the description provides a clear conceptual model of what is returned (legal move squares). It does not mention error cases or prerequisites (e.g., active game), but for a read-only query tool this is sufficient. The sibling context and schema fill in most gaps, making the description nearly 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 only 33%, with `square` already described in the schema. The description repeats the omit behavior exactly without adding new meaning. Required parameters `game_id` and `agent_token` remain unexplained. Given low schema coverage, the description should compensate but does not, offering little additional semantic value for parameters.

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

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

The description clearly states the tool's purpose: to compute legal moves according to pure chess rules, explicitly distinguishing it from evaluation or suggestion. It uses a specific verb ('get') and resource ('legal moves'), and mentions the optional square parameter for filtering, which uniquely identifies its functionality 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?

The description provides clear context for when to use the tool: when you need raw legal move calculation, not strategic advice. It excludes evaluation/suggestion/opinion but does not explicitly name alternatives such as `make_move` or `get_game_state`. While implicit, the guidance is sufficient for an agent to select this tool over the listed siblings.

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 discloses the core effect — updating the presence lease so the frontend sees the agent as alive — but does not mention lease duration, idempotency, or response behavior. Acceptable for a simple liveness ping, but thin.

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 front-loads the action and purpose with no filler. Every word earns its place.

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

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

Complexity is low, but no annotations and no output schema raise the burden on the description. It conveys the core keepalive purpose but omits practical details like call frequency, lease renewal behavior, or return value. Adequate with clear gaps.

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

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

Schema description coverage is only 33%, and the description does not explain any parameters. game_id and agent_token are left entirely to naming inference, while only status_note has a schema description. The description fails to compensate for the low coverage.

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

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

The description uses a specific verb ('Ping') with a clear resource ('game presence lease') and a concrete purpose ('show the frontend that the agent is live, connected, and thinking'). This clearly distinguishes heartbeat from siblings like get_game_state, send_chat, or make_move.

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 implies when to use the tool: when the agent is active and needs to signal liveness to the frontend. It does not explicitly state cadence or contrast with alternatives, but the context is clear enough for a simple heartbeat tool.

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

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

The description discloses useful behavioral expectations: it will connect to a game, return credentials that all other tools depend on, and requires agent_name to be provided. However, with no annotations present, it leaves unclear whether joining is idempotent, whether passing an existing agent_token reconnects, or what side effects a second join may cause.

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

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

Two sentences deliver the core action, the required credential, the return value, and the critical input—all front-loaded with zero filler. The capitalized requirement about agent_name is hard to miss.

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

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

The description is sufficient for the basic fresh-join flow, but it does not resolve the ambiguity of the eight-parameter schema, does not explain reconnection, and provides no output schema. Given no annotations and multiple weak/undocumented parameters at the schema level, this is a noticeable gap.

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

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

The description adds meaningful guidance for agent_name, agent_token, and the invite-code concept, and it stresses that returned tokens are needed everywhere. But the schema has many aliases (gameId, game_id, matchId, match_id, inviteCode) and only 38% parameter description coverage; the description does not clarify which identifier to supply when only a game id or match id is known.

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

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

The description states a specific action—connecting to a game via a given invite code—and names the key returned artifacts: game_id and agent_token. This clearly distinguishes joining from the sibling tools such as create_game, get_game_state, or make_move.

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 explains when to use the tool: when a human has supplied an invite code and you need to join an existing game. It implicitly contrasts with create_game by requiring an existing invite, but it does not explicitly name create_game as the alternative when no invite code exists.

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 provided, the description carries the burden of explaining behavior. It does well by disclosing that illegal moves produce a clear reason and permit retry, and by specifying the thought language requirement based on game state. It omits some side-effect and concurrency details, but the core interaction behavior is well conveyed.

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

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

The description is compact and front-loaded with the core action, then adds behavioral and parameter guidance. The repeated phrasing about not giving a menu or ranked list is slightly emphatic but serves to prevent misuse. Every sentence contributes useful guidance, and it is not bloated relative to the tool's complexity.

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

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

Given 11 parameters, no output schema, and no annotations, the description covers the most important operational details: move submission, illegal retry, thought inclusion, and language selection. The schema already documents fields like expected_ply and idempotency_key, so their absence from the description is acceptable. It is nearly complete for an agent to use the tool correctly.

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

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

Schema description coverage is 82%, which is high, so a baseline of 3 applies. The description adds meaningful semantics beyond the schema by explaining that thought is not optional flavor text, must be genuine, and must be written in the game state's thought_language. It also reinforces that chat is optional and separate from the move itself.

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

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

The description clearly states the tool submits a move the agent has already decided on, with a specific verb and resource. It also differentiates itself from tools that return move lists or menus: 'not a menu, not a ranked list, nothing pre-chosen for you.' This makes its purpose unmistakable relative to siblings like get_legal_moves.

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

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

The description gives clear context for when to call this tool: after deciding on a move, with the expectation that illegal moves will return a reason and can be retried. It also provides guidance on mandatory thought content and language. It does not explicitly name alternatives like send_chat or share_thought, but the implied separation is reasonably 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 of behavioral disclosure. The sentence 'The game stays active until your human responds' adds important non-obvious behavior: the offer does not immediately end the game. This is valuable context beyond the basic purpose.

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

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

The description is two sentences, front-loaded with the main purpose, and the second sentence adds essential behavioral detail without redundancy. Every word earns its place.

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

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

For a simple 2-parameter tool with no output schema, the description conveys purpose and a key behavior, but it lacks any parameter semantics. Given the low schema coverage, the description should have compensated by explaining game_id and agent_token, which it does not. This gap keeps it at a minimum viable level.

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 0%, and the description does not mention or explain the two required parameters (game_id, agent_token). Since the schema also lacks descriptions, the agent receives no additional semantic guidance for these parameters.

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

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

The description clearly states the tool's purpose: 'Propose ending the game as a draw.' This uses a specific verb ('propose') and resource ('draw'), and it naturally distinguishes from sibling 'respond_to_draw' which handles the opponent's response.

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

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

The description provides clear context by saying 'Propose ending the game as a draw,' which implies when to use it. However, it does not explicitly name alternatives or when not to use it, though the sibling 'respond_to_draw' is obviously the counterpart.

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 of behavioral disclosure, yet it only states the bare effect (adds a reaction). It does not disclose whether reactions are visible to all players, whether re-reacting replaces or stacks, whether this mutates shared game state, how agent_token auth works, or what happens on failure (e.g., invalid message_id). For a mutating tool with zero annotation coverage, this is a significant 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 front-loaded sentence with no filler; the action and target are stated immediately. The eight emoji examples are slightly redundant since the schema already lists five of them, but the description remains compact and readable overall.

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 4-required-parameter mutation with no output schema and no annotations, the description gives just enough to invoke the tool correctly (which message, which emoji), but omits expected outcomes, return behavior, and edge cases such as invalid message_ids. It is minimally viable but leaves the agent guessing about side effects and failure modes.

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%: emoji and message_id have descriptions, while game_id and agent_token are bare names. The description adds value by supplying emoji examples and clarifying that message_id refers to a message in chat history, but it contributes nothing for game_id or agent_token. It partially compensates for the coverage gap without fully closing it.

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

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

The description uses a specific verb ('Add') and identifies a concrete resource ('a message in the chat history'), with concrete emoji examples that make the action tangible. It is implicitly distinguishable from the sibling send_chat, since reacting to an existing message differs from sending a new one, but the description never explicitly names that alternative or contrast.

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

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

No guidance is given on when to react versus when to use send_chat or other chat-related tools, nor on any prerequisites such as being in the game or the message_id needing to come from chat_history. The phrase 'in the chat history' is the only weak hint at message sourcing, and the agent is left to infer the appropriate context entirely from 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?

With no annotations, the description must carry the full burden. It discloses that the game ends and the human wins immediately, implying irreversibility, and the phrase 'your own real decision' signals intentionality. It does not detail authorization or response behavior, but those are less critical for this simple 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?

The description is concise and front-loaded with the main action. The additional warning 'your own real decision, not something to do lightly' adds a useful cautionary tone but is not essential technical information, so it loses one point for slight redundancy.

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

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

For a simple resign action with two obvious parameters and no output schema, the description provides essential context: it ends the game and gives the human an immediate win. It could mention the response format or error cases, but these are not critical for a tool of this simplicity.

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

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

The input schema has zero description coverage (0%), and the description does not explain the roles of game_id or agent_token. While the parameter names are self-explanatory, the description fails to compensate for the lack of schema documentation, leaving the agent to infer their meanings.

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

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

The description clearly states the action ('End the game by resigning') with a specific verb and resource, and it distinguishes itself from sibling tools like make_move or offer_draw by emphasizing finality and immediate human victory. The consequence is explicit, leaving no ambiguity about the tool's purpose.

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

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

The description provides strong context: it is a decisive, final action ('not something to do lightly') and explains that the human wins immediately. However, it does not explicitly mention alternatives such as offer_draw or state when not to use it, preventing a perfect score.

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 full responsibility for disclosing behavioral details. It mentions that the decision is the agent's own and to weigh the position, but it fails to mention that accepting will end the game in a draw or that declining continues play. This is a significant omission for a state-changing 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?

The description is remarkably concise, packing the core functionality into a single clear sentence and a brief advisory statement. There is no wasted verbiage, and the front-loaded action is easy to parse.

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?

As a mutation tool with no annotations or output schema, the description needs to set expectations for what happens after the call. It does not explain the consequences of accepting or declining, error conditions, or prerequisites (e.g., a pending offer). The description is adequate for a simple boolean action but lacks the completeness expected for a state-changing operation.

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

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

The input schema has no descriptions, and the description does not elaborate on the parameters. It only hints at the 'accept' parameter through 'accept or decline', leaving game_id and agent_token unexplained. With 0% schema coverage, the description should have provided at least some guidance on these parameters.

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

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

The description clearly states the action (accept or decline) and the object (a draw offer from the human), using a specific verb. It naturally distinguishes from sibling tools like offer_draw, which would be for initiating a draw offer, by specifying that this is a response to an existing offer.

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 establishes the context: responding to a draw offer from the human opponent. It doesn't explicitly list alternatives or exclusions, but the wording implies this tool is only for when a draw has been offered, making the usage clear enough. A more explicit mention of not using this to initiate draws could have improved 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. It discloses a key behavioral trait (usable at any time, not just during agent's turn), but does not mention any restrictions, side effects, or delivery details. This is a minimal but useful disclosure.

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

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

The description is a single, concise sentence that fronts the core action and adds a key contextual nuance. Every word contributes value, and it is immediately understandable without fluff.

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

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

For a simple chat-sending tool, the description covers the primary action and timing nuance, but it omits parameter explanations, return behavior, and any potential limitations. It is minimally adequate but leaves the agent to infer several operational details.

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 0%, and the description only implicitly covers 'message' through 'Say something.' It provides no meaning for 'game_id' or 'agent_token,' leaving the agent to rely on external context. The description fails to compensate for the lack of schema descriptions.

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

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

The description clearly states the tool's purpose: sending a chat message to a human. It also distinguishes itself from sibling game-action tools by emphasizing 'any time, not just on your turn,' making it specific and 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 phrase 'any time — not just on your turn' gives clear context on when to use this tool, explicitly noting it can be used outside the normal turn flow. It does not provide explicit exclusions or alternative tool references, but the usage context is evident.

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 disclose the key side effect: the thought appears live and is visible to the human above the avatar. It does not say whether the thought is replaced or updated, how long it persists, or any rate or visibility constraints.

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 tight sentences with no filler. The action and target are front-loaded, and the second sentence adds the essential live-visibility consequence.

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 4-parameter companion tool, the description covers what the tool does and its core visible effect. It lacks an explicit pointer to send_chat as the alternative for real conversation, but schema definitions carry the parameter details, so the overall context is sufficient.

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

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

The schema already documents thought and is_typing, so the description adds little parameter-level meaning beyond the 'thinking bubble' context. game_id and agent_token remain undocumented and the description doesn't clarify their purpose or format.

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 specific action ('Stream or update') and a concrete resource (the 'internal companion thinking bubble'), and the second sentence grounds it as a live bubble above the avatar. This clearly distinguishes it from send_chat and react_to_chat.

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

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

The description implies when to use it: whenever the agent wants to expose an internal thought live to the human. However, it never names an alternative like send_chat or says when not to use it, so the routing decision is left 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?

With no annotations, the description carries full burden. It discloses the long-poll behavior (checks every couple seconds, up to ~20s), the timeout event, the immediate return with a cursor, and the 'timeout' event. It also transparently notes max_wait_seconds is capped by Vercel limits. Minor omissions like error handling but sufficient for a safe read-only operation (no mutation indicated).

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, dense paragraph that front-loads the main behavior but could be more structured. Every sentence adds information (behavior, cursor optimization, timeout, deterministic loop advice), so it earns its place. Splitting into bullet points might improve readability, but it's not overly verbose for the complexity.

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

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

Given no output schema, the description explains return behavior (events, timeout) but not the full event structure. It covers the main flow, cursor mechanics, and the timeout case. It also gives usage guidance for subsequent calls, which is essential for this polling tool. Missing details like exact event payloads or error codes, but for a waiting mechanism, it is fairly 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 67%, so the baseline is 3. The description adds value beyond the schema by explaining the cursor behavior ('returns any pending event newer than that cursor IMMEDIATELY without waiting') and the hard cap rationale for max_wait_seconds ('Vercel function duration limits, not a design choice'). It also mentions next_cursor (though it's not an exact parameter name), providing loop guidance. This enriches the meaning of the cursor-related parameters.

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 clear, specific verb and resource: 'Holds the connection open... Returns the moment it becomes your turn...'. It explicitly enumerates the four event types it waits for, which distinguishes it from sibling tools like get_game_state (which would not poll) and send_chat (which sends). The purpose is unambiguous and sets it apart.

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

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

The description provides clear context on when to use this tool: for awaiting turn, chat, draw, or game end. It gives explicit guidance on cursor usage ('When a cursor is provided...') and recommends including next_cursor in subsequent calls for deterministic looping. However, it doesn't explicitly state when not to use it (e.g., for immediate state checks), but the polling nature is clear enough.

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