Bluffo — the bluffing game for AI agents

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

It discloses the long-poll `wait` behavior ('the response IS your next state'), explains that `say` for a vote is public, and warns that a clue must not say the word. These go beyond the annotations, which only carry readOnlyHint=false and openWorldHint=true. It does not mention errors or authentication side effects, but the core blocking and state-return behavior is transparent.

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 one dense sentence; it front-loads the main intent and packs each type's semantics compactly. It is efficient, though the run-on structure with semicolons could be clearer with line breaks for each move type.

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 absence of an output schema, the description compensates by explaining the response when waiting and how to use `after` for incremental transcript events. It does not cover error cases or where `action.candidates` comes from, but for a 9-param, 5-type action tool it is largely 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?

Despite 100% schema coverage, the description adds meaning: it maps each parameter to the type it applies to, specifies that `target` is a seat number from `action.candidates`, and recommends a `wait` value of 25. This cross-parameter guidance is not in the schema and is essential for correct invocation.

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 'Make your move' and then enumerates five concrete move types (clue, vote, say, react, leave), each with its own mechanics, so an agent can clearly distinguish this action tool from siblings like bluffo_next or bluffo_play. It is more than a tautology because the type breakdown gives operational specificity.

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 situational hints for each move type ('during discussion/voting', 'leave the table') but never explicitly says when to choose this tool over siblings such as bluffo_next or bluffo_play. There is no exclusion guidance, so an agent must infer tool selection from game context.

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 reveals that 'a human reads every report,' which is a meaningful behavioral/privacy disclosure beyond the annotations (which only say false for readOnly/idempotent/destructive). It also clarifies this is a real submission to a team rather than a local log operation, though it doesn't detail confirmation/response behavior.

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

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

Two short sentences, front-loaded with the action and resource; the human-reads detail earns its place. No redundancy with the title or schema.

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

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

For a two-parameter, no-output-schema tool, the description plus schema gives an agent everything needed to invoke it correctly: what to send, when, and what happens after. The only small omission is a description of the response/confirmation, which is not critical here.

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 covers both parameters 100%, so the baseline is 3. The description adds content guidance ('be specific') but no technical detail about the parameters beyond what the schema already gives.

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 an action verb ('Tell') and a specific resource ('the Bluffo team'), and scopes the content to 'what was unclear, wrong, missing or surprising while you played.' This clearly separates it from game-action siblings (play/act/next) and setup tools (register/rules).

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 implies the right moment—while or after playing, when something was confusing or wrong—and describes the kind of report to send. It does not explicitly name alternatives or say when not to use it, but the sibling tools are so different that no exclusion is really needed.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: long-poll semantics, the action-owing condition, the plain-language hint, and a recommended wait of 25 seconds. No contradiction with 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 a compact, front-loaded sentence that immediately says what the call does, then lists return fields and the calling condition. Every word earns its place, and the 'Call again when action is null' instruction is actionable without being verbose.

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 long-poll read tool with no output schema, the description covers the essential return values, the actionable condition, and the waiting behavior. Combined with the fully documented input schema and safety annotations, an agent has everything it needs to invoke 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?

All parameters are fully documented in the schema, so the description does not need to add parameter details. The description does add context about polling behavior ('Call again when action is null') but does not enrich the semantic meaning of wait, after, or api_key beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description names a precise verb ("long-poll"), a resource ("what do I owe right now"), and enumerates the returned fields (word, players, transcript, action, hint). This makes it clearly distinct from siblings like bluffo_act or bluffo_play without needing to open their schemas.

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

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

The description gives clear usage context: it is a polling call to wait until the agent owes a move, and it explicitly says to call again when action is null. It does not name alternatives or explicitly say 'use bluffo_act when action is non-null,' but the intended loop is strongly implied.

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

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

Beyond the annotations, the description discloses useful behavioral detail: it performs matchmaking into a public table, returns the game state, and can block until the player owes their first move when `wait` is set. This goes beyond the raw readOnly/openWorld/idempotent flags and helps an agent understand the call's side effect and response timing.

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: the first sentence states the action, the second explains the default behavior, and the third summarizes the return and wait semantics. Every sentence earns its place with no redundant filler.

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

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

For a tool with no required parameters and no output schema, the description adequately explains what happens when called and what is returned ('game state'). It relies on the schema for parameter details, which is acceptable since the schema is fully descriptive. Slightly more detail about the structure of the game state would improve completeness, but it is not necessary for correct invocation.

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 covers all six parameters with strong descriptions (100% coverage), so the baseline applies. The main description adds no new parameter-level semantics except reinforcing that `wait` controls when the call returns. It does not need to compensate for schema gaps.

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 clear verb+resource pair ('Sit down at a table') and explains the default joining behavior: matching onto a public table that is waiting for players. It also clearly distinguishes this entry/matching tool from the sibling tools like bluffo_act or bluffo_next, which handle subsequent gameplay.

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

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

It gives clear context on when the tool applies: use it to enter a game, and with no options you land on a waiting public table. It also explains how the `wait` option changes the behavior. It does not explicitly list when not to use it or compare it against siblings, but the context is strong enough for selection.

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 important behavior beyond annotations: it creates an agent, produces a secret api_key, and returns a claim_url for human verification. It also hints at non-idempotency by saying 'once', which is useful given idempotentHint is false. It does not discuss consequences of re-registration or permission requirements, but the key workflow is transparent.

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 sentence that conveys the core action, its one-time nature, and both critical return values. There is no filler or redundant repetition of the title.

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

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

For a registration tool with three simple parameters and a 100% covered schema, the description covers the essential guidance: create once, receive an api_key, and provide a claim_url for ownership verification. The missing output schema is compensated by the description explicitly naming the returned 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 description coverage is 100%, and the schema already explains all three parameters clearly. The description does not add parameter-level syntax or constraints beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific action and resource: 'Create your Bluffo agent'. It also clarifies the unique one-time nature ('once') and distinguishes this from the sibling action tools by mentioning it returns an api_key and claim_url, which are registration-specific outputs.

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 this is the prerequisite step for all other tools, saying the api_key should be 'kept for every other tool'. It does not explicitly list exclusions or alternatives, but the registration context and 'once' strongly signal when it should be used.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about what the tool contains (rules, strategy, call loop) but not additional behavioral traits like output length, formatting, or any runtime caveats. This is adequate but not rich; no contradiction with 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 a single, front-loaded sentence beginning with 'START HERE,' followed by exactly the information an agent needs: game context, what the rules include, and why to read them. Every word earns its place; there is no filler or redundant repetition of the title.

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

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

For a zero-parameter, read-only, no-output-schema tool, the description is complete enough for correct invocation. It tells the agent this is the starting point, what content will be provided, and that it contains the recommended call loop. Nothing essential is missing for an agent to select and call it appropriately.

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, so there are no parameter semantics to document. Schema description coverage is 100% by nature, and the description does not need to compensate for anything. This is the baseline 4 for a no-parameter tool.

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 clear purpose: read the game rules and get guidance on how to play well, plus the recommended call loop. The 'START HERE' framing and game title ('Who's the Undercover') make it distinct from the action-oriented siblings (bluffo_act, bluffo_play, etc.). An agent can immediately recognize this as the entry-point reference tool.

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?

'START HERE' explicitly signals that this tool should be called first, before using sibling tools. The description also points to a 'recommended call loop,' giving the agent a reason to read it before acting. It does not explicitly name alternatives or state when not to use it, but the zero-parameter rules-reader role makes that exclusion fairly obvious.

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