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

It discloses non-idempotency, mutation of shared state (debt row or Hand deck), priority ordering for owed debt, and the exact return shape. Annotations only hint at read-only/destructive status, but the description goes well beyond them, adding meaningful behavioral context without contradicting anything.

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 longer than minimal but every sentence earns its place, covering the invocation rule, procedural details, narrative requirement, alternative, side effects, and return contract. It is front-loaded with the trigger condition and structured into logical paragraphs.

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 side-effectful tool with an empty schema and no output schema, the description is remarkably complete. It explains the trigger, source selection rule, debt precedence, intrusion requirement, consequences, non-idempotent behavior, and return fields—nothing important is left 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?

There are zero parameters, so the schema cannot carry meaning. The description explicitly notes 'Takes no parameters,' which resolves any ambiguity and matches the empty input schema. A baseline of 4 is appropriate for a no-param 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 clearly states the tool triggers the Called Hand when an omen lands doubles, with a specific triggering condition and relationship to cast_omen. It distinguishes this from defiance and other sibling tools by explaining its exact role in the flow.

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 states when to call it ('immediately whenever cast_omen returns doubles=True'), that it is not for the player to invoke, and points to defy_roll as the alternative for fighting the landed fortune. This provides strong usage guidance with clear exclusions.

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?

Discloses idempotency and state mutation beyond annotations: 'Not idempotent: each call rolls fresh dice and increments an internal counter that alternates who narrates the result. Doesn't mutate any other game state.' Also describes the doubles case where no answer is given and the Hand is called. Annotations only provide readOnlyHint:false and destructiveHint:false, so this adds significant value.

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?

Every sentence earns its place, covering purpose, usage, parameter, and behavior. The description is structured logically, front-loading the core mechanic, then usage rules, then parameter semantics, then return values. It is detailed but not redundant.

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

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

With no output schema, the description fully details return values: 'Returns a dict describing the roll: on doubles, {hope, light, dark, doubles: True, reading} — no answer, the Hand is called instead (see call_the_hand). Otherwise {hope, light, dark, doubles: False, direction, gap, texture, complication_rank, complication_meaning, grounds_by}.' It also clarifies the meaning of key fields and side effects, making it complete for an agent.

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 fully explain parameters. It does: 'hope: a plain sentence naming the real stakes being asked about — what the asker hopes is true (e.g. "I hope the guard doesn't notice me").' This adds concrete meaning and an example, going beyond the schema's bare title.

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 explicitly states the tool's purpose with a specific verb and resource: 'Cast an omen: roll two ten-sided dice (light vs dark, compared not summed) to answer a real yes/no question with real stakes.' It clearly distinguishes from siblings by noting 'use draw_unclaimed_card for that instead' for non-yes/no content.

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?

Provides explicit when-to-use and when-not-to-use guidance: 'Call whenever a scene reaches something no one can know in advance — other hearts, hidden things, or the turn of luck — or when a player claims an uncertain, high-stakes action simply succeeded.' It also includes an exclusion and alternative: 'Not for material that just needs new story content rather than a yes/no answer — use draw_unclaimed_card for that instead.'

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, which doesn't convey the side effect or idempotency. The description adds crucial context: it is idempotent, sets a flag, and returns goal_completed as True. It also clarifies the exact timing condition, going well beyond 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?

Each sentence earns its place: purpose, timing condition, prohibition, sibling distinction, idempotency note, and return value. The structure is front-loaded with the purpose and flows logically. No 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?

Given no parameters and no output schema, the description covers all essential information: what the tool does, when to call it, when not to, how it differs from a sibling, and its behavioral properties. This is fully complete for an agent to invoke 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?

With 0 parameters, the baseline is 4. The description explicitly states 'Takes no parameters' and mentions the return value, which is sufficient since there's nothing to explain about arguments. It adds no unnecessary parameter details.

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 starts with a specific verb+resource: 'Mark the current Sitting's Goal as completed', and immediately clarifies the condition ('once the story has actually resolved it'). It also distinguishes from sibling tool draw_goal_card by location in play (start vs later), satisfying the need for differentiation.

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

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

Explicit when-to-use and when-not-to-use: 'Call at most once per Sitting, only after an Omen's grounding has landed... never call this preemptively'. It also names an alternative (draw_goal_card) and explains the boundary (deals vs marks finished). This is textbook usage 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?

Despite annotations (readOnlyHint=false, destructiveHint=false), the description greatly extends transparency: it warns about a ValueError if called prematurely, declares it non-idempotent, details that it adds one debt card per roll taken (win or lose), and resets dice/roll-count state. It also fully explains return fields, including pattern meanings.

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 well-structured: a single-sentence summary first, then clear usage prerequisites, then a detailed behavior/return spec. Every sentence adds value, and the length is justified by the tool's complexity (state mutation, error handling, and a rich 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?

With no output schema, the description fully explains the return dict (final_dice, rolls_taken, pattern, bend, debt_dealt) and the pattern value mappings. It covers the error condition, state mutation, and the ritual lifecycle, making it complete for the tool's complexity.

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 has zero parameters, and the schema is an empty object. The description explicitly states 'Takes no parameters,' and no further parameter guidance is needed. Per the rubric, a baseline of 4 applies for zero-parameter tools, and the description does not add parameter-specific meaning beyond that.

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 precise action: 'Lock in the current defiance dice as final, deal debt, and reset the ritual.' It clearly distinguishes from siblings like defy_roll (the preceding step) and call_the_hand, making the purpose 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?

Explicitly specifies when to call: after defy_roll has been used at least once and rolling is done (whether by choice or after three rolls). It also notes that a subsequent defy_roll starts a fresh ritual, providing clear sequencing.

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

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

Annotations only say readOnly=false and destructiveHint=false, so the description must carry the burden. It goes well beyond that by disclosing non-idempotency, mutation of shared dice/roll-count state, extra debt consequences, and constraints such as requiring keep to be a subset of current dice.

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 detailed but efficient, front-loading the core purpose before explaining the two-phase invocation flow, parameter rules, and side effects. No sentence is filler; the repetition of 'up to three rolls' is minor and reinforces the boundary.

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 moderate complexity and lack of output schema, the description covers all needed information: exact call flow, parameter constraints, state mutation effects, consequences for debt, and return value structure including dice and pattern fields. The reference to defy_resolve for scoring/enforcement also completes the ritual workflow.

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%, so the description must fully explain keep. It does: keep holds die face values to preserve before re-rolling, must be a subset of the current showing dice, raises ValueError otherwise, and must be empty/None on the first roll. This is complete and actionable.

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: 'Roll (or re-roll) the five defiance dice, Yahtzee-style.' It clearly identifies when the tool applies ('when a player wants to fight a landed fortune from call_the_hand') and distinguishes it from the related sibling defy_resolve, which locks in the result.

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 explicit calling instructions: use on the first roll with keep=None, re-roll up to two more times, hold dice via keep, and call defy_resolve when satisfied. It clearly frames the tool within the larger defiance ritual and names the sibling that handles the next step.

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 that the operation is not idempotent, mutates the shared cross, removes a card from the suit's pile, returns a specific dict shape, and that the card's phrase should not be revealed until all four drives are filled. This is strong behavioral context.

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

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

The description is dense but every sentence adds necessary context: purpose, invocation order, uniqueness constraints, blindness behavior, parameter meanings, mutation effects, and return shape. There is no filler or repetition of structured data.

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 has no output schema and only enum-based parameters, the description supplies all needed context: what the tool does, exactly when to call it, what parameters mean, what state changes occur, what errors arise, and what the returned dict contains. It is complete for safe 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?

With 0% schema description coverage, the description fully compensates: it explains suit meanings and suits' names, defines position values as the four drives, and clarifies the semantic roles each suit represents. The parameters are entirely enriched beyond the bare enum 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 uses a specific verb and resource: 'Draw one card, blind, into a position on the Sitting's cross' and distinguishes this from sibling drawing tools by anchoring it to the four-drive character-creation spread. It clearly names what the tool does and the exact context.

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 explicit when-to-use guidance: call once per drive after the player chooses a suit, and in the order Motivation, Seek, Carry, Ends. It also states when not to call it—each position and suit can only be used once, and a reused value raises ValueError.

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 error conditions ('Raises ValueError if called before all four cross positions are filled, or if a Goal has already been dealt'), non-idempotency, mutation of shared state, and the return shape. This goes well beyond what readOnlyHint and destructiveHint already reveal, and it does not contradict the annotations.

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

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

Each sentence adds necessary information: sequencing, comparison to draw_cross_card, error preconditions, state mutation, and return fields. The description is detailed but not padded, and it is organized in short scannable paragraphs.

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?

Since there is no output schema and stateful game rules matter, the description fills an important gap by specifying the returned dict fields, exact call timing, before-conditions, and post-call handoff. No essential operational detail appears 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?

The tool has zero parameters and no required fields, so the schema is already complete. The description explicitly confirms 'Takes no parameters' and instead places invocation correctness on preconditions and state, which is the appropriate level of guidance for a 0-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 opens with a specific action: 'draw one card face-up from whatever is left across all four suit piles' and clearly identifies the goal-card purpose. It also distinguishes itself from draw_cross_card by noting the combined-pile behavior and immediate reveal, which prevents sibling confusion.

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 precise sequencing: call once during the Sitting, after all four draw_cross_card calls, and after the player has described their character. It also explicitly contrasts with draw_cross_card and directs the next step to record_goal_interpretation, giving clear when-to-use and next-action guidance.

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

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

Beyond the annotations, the description discloses that the tool is not idempotent, removes a distinct card from a shared shuffled deck, auto-reshuffles when exhausted, and returns a dict with six specified fields. These are important behavioral details not available from readOnlyHint/destructiveHint alone.

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 front-loaded with the core purpose and every sentence adds needed guidance: when to use, when not to use, how to handle the phrase, non-idempotence, and return structure. It is longer than a one-liner, but the content is all operational and necessary.

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?

Because there is no output schema, the description fully covers the return value by listing the dict fields. It also explains deck behavior, reshuffling, and the intended narrative workflow, making the tool self-sufficient for an agent to invoke 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?

The tool takes no parameters, and the schema already reflects this with an empty properties object. The description explicitly confirms 'Takes no parameters,' so there is no parameter semantics gap to compensate for. Baseline 4 is appropriate for a zero-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 clearly states the tool's action: 'Draw one card from the Fortuneteller's Hand deck to open or refuel a scene with new story material.' It names the specific resource (Fortuneteller's Hand deck) and distinguishes its purpose from cast_omen, which is explicitly reserved for yes/no questions.

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 explicit invocation guidance: call at the start of every new scene, and mid-scene when the story needs new material. It also names the alternative for yes/no questions ('use cast_omen instead') and instructs the agent to read the returned phrase before narrating anything else.

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 and destructiveHint=false. The description adds specific error behavior (raises ValueError if no character named or name mismatch) and return format. It doesn't contradict annotations, and adds useful behavioral context beyond the safety flags.

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?

Description is longer than typical but every paragraph adds essential info: purpose, usage context, error semantics, return structure. Well-structured with clear paragraphs. Slightly verbose but justified.

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 simple tool, it fully explains what it returns, when to call, error casesable. No output schema, so description covers return dict. Sibling tools are distinct (mutating actions vs this read-only query). 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 has 0% description coverage, but the description comprehensively explains player_name: exact match requirement, error conditions, and relationship to name_character. This is far beyond 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?

Clearly states it reads the current character sheet with specific contents (cross, goal, debt row, goal_completed), and distinguishes itself from siblings as read-only state access. The verb 'Read' is specific and the resource is well-defined.

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 'Call any time you need to check saved state rather than re-deriving it' and gives concrete examples like checking interpretation before complete_goal or checking goal_completed to decide campaign closure. Also states read-only nature and error conditions.

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?

Discloses non-idempotency, overwriting behavior, lack of confirmation/uniqueness check, and the exact return format. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds specifics beyond these (overwrite semantics, no uniqueness check) without contradiction.

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 yet complete: front-loaded purpose, automatic-call note, usage guidance, idempotency warning, and return format—all in a few well-structured sentences.

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 1-parameter tool, it covers purpose, automatic invocation, when to call directly, behavior (overwrite, no checks), and return schema, leaving no ambiguity for the agent.

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 zero schema description coverage, the description explains player_name is the player-chosen name with no format constraints, adding meaning not in the schema. It also clarifies the return value with that parameter.

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 'Set the name of the character being created for a new Sitting' with a specific verb and resource. It also distinguishes itself from siblings by noting it's automatically called and exists for other tools to validate against.

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 explains when it's called automatically, that users typically don't need to call it, and provides clear guidance for when to invoke it directly (renaming outside the normal flow). This distinguishes it from 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?

The description discloses that the tool overwrites existing interpretations (not idempotent), raises an error if called at the wrong time, and returns the full updated Goal card dict. These details go beyond the annotations (readOnlyHint false, destructiveHint false) and provide important behavioral context.

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

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

The description is well-structured and concise, with each sentence serving a purpose. It avoids fluff and presents information logically: purpose, timing, parameter details, error conditions, and return value. The repetition of key points is minimal and does not detract from clarity.

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 sparse schema (only a string parameter with no description) and no output schema, this description provides complete context: what the tool does, when to call it, what the parameter means, what errors can occur, and what it returns. It also relates to other tools (draw_goal_card, complete_goal, get_sheet), making it self-contained.

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 thoroughly explains the 'interpretation' parameter: it should be a plain-language sentence or two capturing what the Goal means, and explicitly states it should not be a verbatim quote. This adds significant meaning beyond the schema's simple string 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 clearly states the tool's purpose: to save the player-and-Claude-agreed meaning of the Goal card. It distinguishes itself from siblings by explaining its role in the flow (e.g., it feeds into complete_goal) and provides specific context about when it is used.

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 states when to call: once, during the Sitting, right after the player has answered and Claude has reflected. It also notes a precondition (must be after draw_goal_card) and an error condition (raises ValueError if called too early), giving clear usage boundaries.

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