Plot Speaks

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

The description adds useful behavioral details beyond the annotations: it returns a verdict line starting with 'Correct.' or 'Innocent.' and the matched name, and it records the accusation and verdict anonymously. The annotations already indicate it is a non-read-only, non-destructive, non-idempotent operation, and the description complements this well, though it does not discuss repeated-call behavior or error cases.

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

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

The description is three tight sentences: purpose, return value, and side effect. It is front-loaded and every sentence provides useful information with no wasted text.

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 three-parameter mutation with no output schema, the description covers the core behavior, return format, and anonymity side effect. It leaves minor gaps around duplicate accusations and usage alternatives, but overall it is complete enough 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?

Schema description coverage is 100%, so each parameter is already documented. The description mentions the accused person and matched name but does not add syntax, format, or constraint details beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: it checks a formal accusation in a Plot Speaks mystery. It also explains the return value and side effect, making the purpose clear, but it does not explicitly distinguish this tool from siblings like game_answer or reveal_solution.

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 the tool is used when a user makes a formal accusation in a mystery, but it does not explicitly state when to use it versus alternatives or when not to use it. The context is clear enough for an agent to infer, but usage guidance is only 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?

The annotations declare a non-read-only, non-idempotent, non-destructive mutation, and the description adds real behavior beyond that: returning the scene to narrate plus following choices, returning the ending, and the rewind semantics of go_back. It stops short of stating what happens on an invalid or unmatched choice, or whether rewind discards prior path history.

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

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

Three tight sentences, front-loaded with the primary advance-the-story behavior, then the resume and rewind variants. Nothing is repeated and nothing is padding.

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 present, the description carries return-value disclosure and does it well by naming the three possible outcomes. The remaining gap is failure behavior and any constraints on whether go_back is allowed before an ending, but for a 4-parameter tool this is close to 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 100%, so parameter meanings are already documented; the description nevertheless adds mode-level semantics the schema does not — absence of choice means 'resume' and go_back means 'return to last choice and choose again'. That is genuine added value over the structured fields.

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

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

States a specific verb and resource — it advances a Plot Speaks choose-your-path story by the player's choice — and explicitly names what comes back (next scene and choices, or the ending). It is clearly separable from siblings such as pick_for_me or start_story because it is driven by a player-supplied choice within an existing play.

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 spells out three distinct call modes: pass a choice to advance, omit choice to resume and get the path so far, and set go_back to rewind to the last choice after an ending. That is concrete when-to-use guidance, though it never names a sibling alternative (e.g. pick_for_me) as the option when the player has no answer of their own.

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 indicate a non-read-only, non-destructive mutation. The description adds useful context: it explains what gets added (plays with their outcomes and trivia marks) and notes that plays already on another account are left alone, clarifying overwrite behavior. It does not mention permissions or error handling, but adds value 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?

The description is two sentences, front-loading the target user and action. It is efficient with little redundancy, though the parenthetical repetition of 'the play ids from this conversation' is slightly redundant with the schema.

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

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

Given the tool's simplicity (one parameter), presence of annotations, and no output schema, the description provides sufficient context: it covers the trigger scenario, what is added, and a key constraint. It could mention idempotency or error cases, but those are largely covered by annotations.

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

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

Schema coverage is 100%: the single parameter play_ids is fully documented in the schema. The description repeats the parameter's source ('play ids from this conversation') but adds no new semantic details beyond what the schema provides, so 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 states a specific verb ('adds') and resource ('plays') and clarifies the scenario ('for a player who has just signed in', 'plays they made earlier without an account'). It does not explicitly name or contrast with sibling tools, but the purpose is clear enough to distinguish from typical play creation or retrieval tools.

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 usage ('For a player who has just signed in') but does not specify when to use this tool versus alternatives (e.g., start_story, my_history) or any exclusions. The context is clear but lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the agent knows this mutates state and is not idempotent. The description adds that the answer is scored and the clue advances, which is useful behavioral context, but it does not explain consequences of repeated submissions, invalid-answer handling, or side effects on scores beyond the headline statement.

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 core purpose is front-loaded, but the description is a single long run-on sentence that enumerates many game modes without bullets or paragraph breaks. The content is largely useful, but the lack of structure makes it harder to scan than 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?

For a tool with no output schema and many game-specific answer formats, the description covers the important input variations thoroughly and indicates the return is a ruling or next clue step. It could say more about error handling or what happens on an incorrect answer, but the essential calling guidance is present.

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

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

Schema coverage is 100%, establishing a baseline of 3, but the description goes far beyond the schema's generic 'What the player said' by giving concrete accepted answer formats for each game mode (e.g., 'the fours', 'roll again', 'keep 3 3 5', 'take' or 'steal'). This substantially reduces ambiguity for the answer 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 states a specific verb and resource: checks a player's answer to the open trivia clue, scores it, and returns the ruling or next step. It is clearly distinguishable from siblings like game_challenge or get_cue, though it does not name alternatives explicitly.

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

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

The phrase 'open trivia clue' provides clear context for when to call this tool, and the per-game enumeration clarifies the expected usage. However, it does not state when to avoid this tool or name alternative tools for related actions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful behavioral context by explaining what state is returned across game variants, which is valuable since there is no output schema.

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

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

The description is front-loaded with the main purpose and contains no filler. However, the long parenthetical listing game-specific variants is dense and harder to scan than 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?

With no output schema, the description does a good job explaining what is returned: scores, categories, values on the board, and variant-specific state. It is complete enough for an agent to know what to expect, though usage context is still missing.

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

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

Schema coverage is 100%, and both required parameters (slug and play_id) are described in the schema. The description does not add meaning beyond the schema for these parameters, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource: returns a Plot Speaks trivia game's scores and remaining board state. It clearly distinguishes the tool as a state-reading board view rather than an action tool, even without naming a specific sibling.

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 does not explicitly say when to use this tool versus alternatives such as game_question, game_answer, or reveal_solution. It implies usage by describing returned state, but gives no conditions, prerequisites, or 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?

With only terse annotations, the description carries real weight here and delivers: it explains the 2-of-3 majority mechanism, the per-clue rate limit, and that the tool reads back the ruling ('says what was heard'). That is exactly the kind of non-obvious behavior — a stateful, non-idempotent status change with a quota — that annotations alone (readOnlyHint=false, idempotentHint=false) cannot convey.

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

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

Three tightly packed sentences, front-loaded with the core action and effect, then the constraint, then the mode-specific variant. No sentence is filler — each one adds a rule or a behavior the agent could otherwise get wrong.

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 mutation with no output schema, the definition covers what the tool does, what changes, and the rate limit. Minor gaps remain: it doesn't say what happens if there is no prior ruling or the per-clue attempt is already spent (error vs. no-op), which matters for an operator with destructiveHint=false but a real state effect.

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

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

Schema description coverage is 100%, so both parameters (slug, play_id) are already documented in the schema, including that play_id comes from start_story. The description adds no further parameter meaning, so the baseline 3 applies; the phrase 'the last ruling' implies how play_id is scoped but does not say it explicitly.

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 verb ('challenges') and a specific resource ('the last trivia ruling'), and describes the outcome mechanic (three models judge, ruling flips on 2-of-3). It also distinguishes a second mode — timeline games re-check the last placement — so an agent can tell this apart from game_answer or check_accusation without opening the schema.

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

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

The condition for use is clear (dispute the most recent ruling) and a hard constraint is stated explicitly ('Once per clue'), which prevents repeat-call mistakes. It stops short of naming the sibling an agent should call instead when the goal isn't to dispute a ruling (e.g. answering again via game_answer), so it does not reach a 5.

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

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

Beyond annotations, it discloses concrete state effects: it opens a clue, only opens the final once the board is clear, gives up the open clue on "skip", closes a survey question after three strikes with "no steal", deals the first card in a timeline game, and sets up rules/players. This is rich behavioral context for a non-read-only, non-idempotent 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 core purpose is front-loaded, but the description is a single dense paragraph with nested parentheticals and mode-specific clauses that are hard to scan. Most content earns its place for a multi-mode tool, but the structure could be much clearer.

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

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

For a complex multi-mode tool with four parameters and no output schema, it covers the main modes, special category values, and the key return caveat that the answer is not returned. It still omits error behavior and the optional value parameter's role, so it is strong but not fully complete.

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

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

Schema coverage is 100%, so the schema already documents slug, play_id, value, and category. The description adds useful special-value semantics for category, but it largely repeats the schema's category examples and says nothing about the optional value parameter or slug, so the 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 opening states a specific verb and resource: it opens one clue on a Plot Speaks trivia board and returns its text, not the answer. That distinguishes it from game_answer, but the description never explicitly names sibling alternatives, and the multi-mode sprawl makes the core purpose slightly less crisp.

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 detailed mode-specific usage: category "final" when the board is clear, "next"/"skip"/"no steal" in survey or letter games, deck name in timeline games, and "rules"/"players" in Worms!/Yacht/Pigs!. It lacks explicit when-not-use guidance or named alternatives, so it is strong but not complete.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, and the phrase 'so a passenger following along sees the scene reached' loosely accounts for the side effect of advancing play progress. However, that side effect is only implied, and nothing is said about behavior when the cue or slug doesn't exist.

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 clauses: the return payload first, then the play_id instruction. No filler, though the phrase 'from a Plot Speaks adventure' spends words on flavor that could have carried error or prerequisite information.

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

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

With no output schema, the description usefully names what comes back (scene text and narrator notes), and the optional play_id is explained. Missing only failure/edge-case behavior for an invalid cue id or slug.

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

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

Schema description coverage is 100%, so cue format (S1, S3b) and slug are already documented. The description adds the rationale for play_id ('so a passenger following along sees the scene reached'), slightly exceeding the schema's 'play id from start_story', but slug and cue get no added meaning.

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

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

States a specific verb and resource (returns a cue) and enumerates the payload: scene text plus narrator notes. It doesn't name any sibling tool or contrast with adjacent flow steps like choose or game_board, so sibling differentiation is left implicit.

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 sentence about play_id implies the tool is called while a group follows along in a play, which hints at context, but there is no explicit when-to-use, when-not-to-use, or reference to an alternative tool for fetching scene content.

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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: results arrive three at a time with a one-line pitch, and the page argument walks forward. It stops short of describing the exact response object or what happens at the end of the catalogue.

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

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

Front-loaded with the core purpose and pagination rule, which is good, but the middle is one long run-on enumeration that largely duplicates the enum values already in the schema. The collection and kind lists could be trimmed without losing information an agent needs.

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 9-parameter, all-optional read tool with no output schema and full annotation coverage, the description covers pagination flow, grouping behavior, and every filter family. An agent could call it correctly from this text; only the end-of-list and return-shape details are missing.

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

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

Schema description coverage is 100%, so every parameter is already documented with enums and bounds. The description mostly restates those filters (collection names, kinds, max_minutes) rather than adding syntax or edge-case meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Lists the Plot Speaks stories and games that can be played by voice') plus the exact result shape ('three at a time with a one-line pitch each'). That distinguishes it cleanly from siblings like pick_for_me and start_story, which select or launch rather than enumerate.

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

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

Gives concrete usage contexts: narrow by collection/length/new/kind, and 'use group_by_category without a page for the whole catalogue under kind headings.' It does not explicitly say when to prefer pick_for_me or start_story instead, so there is a gap, but the browsing-vs-selection boundary 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?

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds useful context: results are newest-first, include how each play ended, and require sign-in, with a defined fallback when unauthenticated.

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 core return behavior and authentication condition are front-loaded.

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 single-optional-parameter read-only listing tool, the description covers the key behavioral facts: authentication requirement, ordering, and what each result includes. Minor gaps like pagination or exact return shape are acceptable given the simple schema, though no output schema exists.

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 only parameter, limit, is fully described in the schema with default and bounds. The description adds ordering context but does not enrich limit semantics beyond what the schema provides, so 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?

States a specific verb and resource ('Returns what a signed-in Plot Speaks player has played'), plus scope details: newest first and how each ended. This differentiates it from siblings like list_stories and review_story.

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?

Implies the tool is for viewing a signed-in player's play history, and notes the unauthenticated path tells users how to get an account. However, it does not explicitly compare against alternatives such as list_stories or say when not to use it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the description's job is to add content context — it does, by spelling out exactly which three components come back and how each flag modifies that set. It stops short of clarifying whether 'spoken' means audio or transcribed text, which matters for an agent's next step.

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, zero filler, payload contents front-loaded before the flag modifiers. Nothing repeated and nothing that could be cut.

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 carries the return-value burden and does so by enumerating the returned parts. The only gap is that 'spoken' leaves the response medium (audio vs. text) ambiguous for what is ostensibly an audio-oriented tool.

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

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

Schema description coverage is 100%, so both flags are fully documented in the schema itself. The description restates the effect of skip_intro and instructions without adding format, default, or interaction details beyond what the schema already provides — the baseline case.

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

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

States a specific resource and enumerates what the return payload contains: spoken introduction, question, and category menu with example titles. This clearly distinguishes it from siblings like list_stories or start_story, which perform the actions this welcome merely offers.

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 this is the entry point ('the Plot Speaks welcome') and explains when each flag applies, but never explicitly says 'call this first' or names an alternative to use instead in any circumstance. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world operation. The description adds useful output-cardinality context by saying it suggests ONE item based on mood, time, and players, but it does not explain return format, selection logic, or determinism beyond the annotation.

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 tightly written sentences with no filler. The core action and usage condition are front-loaded and 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?

For a read-only recommendation tool with five optional, fully schema-documented parameters, the description provides enough context to invoke it correctly. It states the input basis and that exactly one suggestion is returned, though it does not detail the result shape.

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

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

Schema description coverage is 100%, and each parameter is well documented in the schema, including collection options and all_ages suitability. The description mentions mood, time, and players, but adds no parameter meaning beyond the schema and omits all_ages and collection.

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 (suggests), resource (ONE Plot Speaks story or game), and timing/context (to play now). It implies a recommendation role rather than listing, opening, or starting, but does not explicitly name sibling alternatives to distinguish itself.

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 a clear when-to-use condition: "Use it when they aren't sure what to play." It does not state when not to use it or name alternatives such as list_stories or choose.

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 the play_id dependency, the one-rating-per-play uniqueness constraint, and the minimum content requirement of stars or a verdict. It also notes that feedback is read by the people who make Plot Speaks. It does not describe what happens when a duplicate rating is submitted or what the call returns, but the annotations already cover mutability and idempotency signals.

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 action and then lists the rating components efficiently. It is a single dense sentence, which makes it slightly heavy to parse, but every clause (play_id, one rating per play, stars/verdict requirement) carries useful information.

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

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

For an 8-parameter mutation tool with no output schema, the description covers the required story and play_id, the main rating fields, the verdict workflow, and the uniqueness constraint. The main gap is that the optional 'wish' parameter is not mentioned and no failure/duplicate behavior is described, but the schema fully documents all parameters and annotations cover the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics not obvious from individual schema fields: the 'stars or a verdict (or both)' validation rule, the intended meaning of verdict for stories under test, and the spoiled flag as 'whether anything was given away too early.' It does not mention the 'wish' parameter, leaving that entirely to the schema.

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

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

The description opens with a specific verb and resource: 'Saves a rating and feedback for a Plot Speaks story the user has just played.' It enumerates the rating content (stars, spoiled flag, comment, feedback, verdict), so an agent knows exactly what this tool records. It doesn't explicitly name a sibling such as review_story to distinguish scope, but the 'just played' / play_id framing implicitly separates it from story-writing tools.

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 concrete prerequisites and constraints: 'Needs the play id from start_story; one rating per play; stars or a verdict (or both).' It also conditions verdict use on 'a story still being tested.' It does not explicitly say when to use this tool versus review_story or write_story, so there is no exclusion guidance.

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

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

Annotations already declare the write/non-destructive/non-idempotent profile, and the description adds meaningful context beyond that: the record is a request routed to maintainers rather than an immediate team creation, and it must be user-initiated. It does not mention duplicate submissions or what the caller gets back, which is a minor gap given idempotentHint=false is already declared.

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, zero filler, and the core action is front-loaded ahead of the consent precondition. Every clause carries information an agent needs.

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 2-parameter write with no output schema, the description covers what it does, who consumes it, and the conversational gate. What is missing is post-call behavior — whether the player should be told anything or whether repeat requests are deduplicated.

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

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

Schema description coverage is 100%, so both parameters (team, note) are already fully documented with length limits and intent. The description adds no syntax, format, or normalization guidance (e.g. league naming conventions) beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Records a player's request for a sports team that ... doesn't cover yet,' and names the consumer ('the people who maintain the database'). It implicitly separates itself from team_roster by scoping to teams that don't exist yet, but never names a sibling or states the contrast explicitly.

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

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

'Only after the player says they'd like it added' is an explicit, actionable precondition that tells the agent exactly when to fire. There is no when-not guidance or named alternative (e.g. use team_roster to check coverage first), which keeps it short of a 5.

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

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

Annotations mark this as a non-read-only, non-idempotent operation, and the description supplies the missing context: it 'Records that the play ended in a reveal,' disclosing the state side effect. It does not address what happens on a repeated call, which matters given idempotentHint=false, so it stops short of full 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?

Two sentences, no filler. The return contents come first and the precondition follows, matching how an agent needs the information ordered.

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

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

There is no output schema, but the description enumerates what comes back (culprit, motive, clues, character outcomes) and notes the recorded side effect, so nothing essential is missing for a 3-parameter tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to gave_up by tying it to the 'gives up / wants the answer without accusing' scenario rather than leaving it as a bare boolean. slug and play_id are left entirely to the schema, which already documents them.

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

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

States a specific verb and resource ('Returns the full solution of a Plot Speaks mystery') and enumerates the payload (who did it, why, clues, character fates). This clearly separates it from siblings like check_accusation or game_answer, which handle accusation logic rather than the full solution.

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

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

Gives an explicit gating rule: only after the player has accused someone, or when they give up / ask for the reveal, and maps that second case to gave_up: true. An agent knows exactly when this tool becomes legal to call.

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 readOnly/idempotent/non-destructive/non-open-world, and the description adds real value beyond that: an explicit privacy guarantee ('Nothing sent is stored') and a statement of what comes back (status, findings with line numbers, fair-play checklist).

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

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

Three dense sentences with no filler; the core check behavior is front-loaded, the conditional secrets.md behavior next, and the return/privacy note last.

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

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

No output schema exists, and the description compensates by naming the returned status, line-numbered findings, and checklist. Combined with full schema coverage and safety annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: that supplying secrets_md conditionally unlocks the answer-key checks, including culprit-giveaway detection. Only the slug parameter's purpose is left solely to the schema.

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

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

States a specific verb+resource: runs format checks on story.md and, when secrets.md is supplied, answer-key checks including culprit leakage. Clear what it does, though it never names a sibling (e.g. submit_story) to differentiate from, so a 4 rather than 5.

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

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

Gives clear triggering context: use on a draft story.md, add secrets.md for the deeper fair-play checks. It doesn't explicitly exclude alternatives or say 'do not use for submission', so it stops short of the 5 bar.

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, openWorldHint=false, destructiveHint=false, so safety is mostly covered. The description adds value beyond them: it states the return shape ('Returns each die and the total') and explains the non-obvious `hidden` behavior — the result is visible only to the agent, not the players — which the annotations say nothing about.

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: the action plus notation examples first, the return contract second. Example density is high but every token maps to a distinct notation the agent must be able to produce; nothing is redundant.

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

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

For a read-only dice roller with full parameter documentation and an explicit return statement, an agent has enough to call it correctly. Minor omissions remain: whether rolls are logged to the story/history, and any bound on dice count or modifiers (the schema caps length at 40 but the description doesn't mention limits).

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns more by documenting the dice grammar beyond the schema's single '1d20+5' example — advantage ('adv 1d20+3'), disadvantage ('dis 1d20'), and drop-lowest ('4d6 drop lowest'). These notations are otherwise unstated anywhere and are essential to invoking the tool correctly.

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

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

Specific verb + resource: 'Rolls dice for a Plot Speaks campaign or adventure on the server', immediately scoping the tool to the correct product context. Concrete dice-notation examples make the purpose unmistakable. No sibling is named, but none of the listed siblings could plausibly be confused with a dice roller.

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

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

Usage is implied by 'for a Plot Speaks campaign or adventure' and the `hidden` example (world clock, hidden table), which hints at when a roll should be secret. But there is no explicit when-to-use vs. when-not-to-use guidance and no named alternative or prerequisite (e.g., must a story be active first?).

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

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

Annotations declare readOnlyHint=false and idempotentHint=false; the description usefully confirms the write side effect ('Records an anonymous play'), which is exactly the context the annotation bar asks for. It also discloses the two-chapter one-at-a-time behavior. It stops short of clarifying whether repeated calls create duplicate plays, which matters for a non-idempotent tool.

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

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

Two sentences, front-loaded with the action and followed by the return shape; no filler. The parenthetical is dense but earns its space by summarizing the script payload.

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 carries the return contract and does so adequately (script contents plus play id). For a 9-parameter, non-idempotent entry-point tool the remaining gap is interaction between chapter and play_id on resume versus start, which the description only partially covers.

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

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

Schema coverage is 100%, so the schema already documents slug-vs-title, chapter, play_id and every code parameter. The description restates chapter-at-a-time and play id but adds no syntax or precedence rules (e.g. what wins when slug and versus_code are both sent). Baseline 3 applies.

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

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

Names a specific verb+resource ('Loads a Plot Speaks story by slug or title') and states the two outputs (script and play id). It does not name the sibling it supersedes (list_stories, open_plot_speaks), so the agent must infer the boundary from the sibling list alone.

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

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

The 'starter' role is only implied by 'Records an anonymous play' and the chapter/play_id relationship described in the description. There is no explicit when-to-use-this-vs-alternatives guidance naming open_plot_speaks or list_stories, which an agent would need to pick correctly.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and 'Changes nothing' merely restates them — but the description adds genuinely new behavior: the three possible states (waiting, approved with link, not accepted with reviewer note). It stops short of saying what happens when the id/code do not match or whether that surfaces as an error or a not-found state.

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

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

One compact sentence with the safety cue front-loaded and the outcome branches ordered logically. The bookended 'Read-only... Changes nothing' is mild redundancy, but nothing else is wasted.

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

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

With no output schema, the description carries the return-value burden and does so by naming all three result states. The remaining gap is failure behavior when the id or claim code is wrong or unknown, which an agent would want to know before calling.

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

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

Schema description coverage is 100%, so both parameters are already documented as coming 'from the receipt'. The description only adds the matching semantics ('when its submission id and claim code match'), which is modest value over the schema — baseline 3 applies.

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

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

The description states a specific verb and resource ('Shows where a story submitted to Plot Speaks stands') and makes clear this is a status lookup keyed by submission id + claim code, which cleanly separates it from siblings like submit_story, withdraw_submission, and list_stories.

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 an implied precondition (a receipt-derived submission id and claim code must match) and enumerates what you learn, but it never explicitly says when to use this versus alternatives such as my_history or list_stories, nor when not to use it (e.g., no claim code on hand).

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?

Goes well past what the annotations declare: names the format checks, safety screen, daily limit, the pending-approval staging behavior, and the returned one-time claim code for withdrawal/updating. It never spells out what makes this destructive (e.g., that replacing overwrites the earlier submission irreversibly) or failure behavior when limits are hit, leaving some annotation-relevant context unstated.

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

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

Three tightly packed sentences, front-loaded with the action and scope, then behavioral consequences, then the replacement variant. No 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?

All seven parameters are documented in the schema, and the description fills in return values (submission id, one-time claim code) despite there being no output schema. Nothing material for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that replaces_id and claim_code must be used together to replace a prior submission, and that the claim code also serves withdrawal/updating.

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

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

Specific verb (submits) plus resource (a finished Plot Speaks story) with scope stated up front. It also distinguishes itself from write_story and review_story by noting human approval is required and that nothing is public yet.

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?

Clear about when to call it (finished story, credited to a chosen name) and when to use replaces_id/claim_code to update an earlier submission. It never names sibling alternatives like withdraw_submission or list_stories, so exclusions are implied rather than explicit.

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

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

Annotations already cover readOnly/destructive safety, so the description's job is incremental. It does add real context: the external data source (ESPN) and the fact that it is the *current* roster, which explains the non-idempotent hint. It stays silent on failure modes — unknown or ambiguous team names, stale data, or network dependency — which matter for an external fetch.

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

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

One front-loaded sentence carrying source, scope, and return contents, followed by a short clause on the input convention. No filler, no restatement 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 one-parameter read tool with annotations and no output schema, the definition covers source, returned fields, and input convention — enough to call it correctly. The remaining gap is what happens when a team name isn't recognized, which an agent would likely need to recover gracefully.

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

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

Schema coverage is 100% and the single parameter already carries the description "The team, as the player named it," so the schema does the heavy lifting. The description's "as the player says it" restates rather than extends that, giving no extra detail on fuzzy matching, accepted formats, or examples.

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

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

Specific verb plus resource plus payload: "Reads a sports team's current roster from ESPN" and names exactly what comes back (players by position with numbers, head coach). It is clear what the tool does, but it never contrasts itself with the similarly named sibling `request_team`, so an agent must guess which one to reach 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?

"for Plot Speaks Team Trivia" gives a situational frame, and "Takes the team's name as the player says it" hints at when/how to call it. There is no explicit when-not guidance and no routing to alternatives such as `request_team` or `game_question`, so usage is only 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?

Annotations already declare destructive, idempotent, non-readOnly, so the safety profile is known; the description still adds the real precondition that id and claim code must match, and the auth-based exception. It does not say whether the deletion is recoverable or what happens to the story afterwards, which is the remaining behavioral 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?

Two sentences, front-loaded with the destructive action and its scope, followed by the authentication shortcut. No filler or 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 destructive tool with no output schema, it covers the match precondition and both invocation paths, which is what an agent needs to call it correctly. It omits post-conditions such as irreversibility or effect on the published listing, a minor but real 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?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the claim code is not merely required but must *match* the submission, and the signed-in writer can omit it entirely. That conditional logic goes beyond the field-level text.

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

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

States a specific verb and resource ('Deletes a story submitted to Plot Speaks') and scopes it precisely to pending or published submissions. It is clearly distinguishable from siblings like submit_story or submission_status without opening a schema.

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

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

The description implies when the tool applies (withdrawing one's own submission, with the signed-in shortcut on the account connector), but it never states when not to use it or which sibling to use instead for checking status before withdrawing. Usage context is inferable but not explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context by detailing what the returned state contains (HP, spell slots, quests, etc.), which is useful behavioral information beyond annotations. It doesn't cover error conditions or precedence between lookup methods.

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 well-structured sentence: it front-loads the core purpose and then elaborates with a compact, comma-separated list of state components. Every part earns its place without 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 read-only tool with no output schema, the description adequately explains the return contents. It could be improved by clarifying precedence if both play_id and resume_code are provided, but overall it provides enough 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 coverage is 100%, so all parameters are documented in the schema. The description restates that a play id or the 'three-word' resume code can be used, but this is already present in the schema descriptions. No additional semantics are provided beyond what the schema offers.

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

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

The description states a specific verb ('Returns') and resource ('campaign's state'), and enumerates what is included (day, place, party stats, etc.). It doesn't explicitly contrast with sibling tools like world_update or open_plot_speaks, but the purpose is clear from the text.

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 by listing two lookup methods (play id or resume code), but gives no explicit when-not conditions or alternatives. It doesn't tell an agent when to prefer this over world_update or check_accusation.

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 readOnly=false, destructive=false, idempotent=false, and openWorld=false. The description adds useful behavioral context beyond those annotations by stating that rule-violating changes are refused with an explanation and by noting constraints like 'the dead stay dead.' It still does not describe authentication, rate limits, or return behavior, but the added validation semantics are meaningful.

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 front-loads the core purpose in the opening clause and follows with a compact list of supported updates. It is somewhat dense but appropriately sized for a tool with 10 parameters, and the second sentence about refusing invalid changes 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 mutation tool with no output schema but 100% schema description coverage, the definition gives enough context to understand that it records campaign events and rejects rule-invalid changes. It omits return-value details, but no output schema exists, and annotations cover safety and idempotency traits.

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

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

Schema description coverage is 100%, so the input schema already documents all 10 parameters in detail. The description lists many of the same categories (characters, damage, healing, items, gold, rests, location, day, NPCs, quests, initiative, note), but it does not add syntax or edge-case meaning beyond the schema. 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 states a specific verb, 'Records,' and resource, a Plot Speaks campaign, and enumerates the kinds of updates it handles. It is clearly a mutation tool for campaign state, but it never names or distinguishes itself from likely siblings such as world_recall, so it falls short of the top score.

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

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

Usage is implied by 'Records what happened in a Plot Speaks campaign,' which suggests using this tool to log campaign events. However, there is no explicit when-to-use guidance, no exclusions, and no routing to alternatives such as world_recall or other game 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real substance: the returned package contains a public story.md plus a private answer key (secrets.md), and human review gates publication. The public/private split and the human-in-the-loop step are exactly the kind of context annotations cannot express.

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 — purpose first, then the contents of the return. The nested parenthetical explaining story.md/secrets.md makes it slightly harder to parse than necessary, but every clause carries information.

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

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

With no output schema, the description correctly spends its budget enumerating what comes back (introduction, drafting/review approach, format template), which is what the agent needs. It falls short only in not connecting the two input parameters to differences in that returned material.

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 both parameters are fully enumerated with defaults documented in the schema, so baseline is 3. The description adds nothing about how genre or length change the returned material, so no credit above baseline.

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 ('Returns material for writing a Plot Speaks story') and crucially corrects the likely misreading of the name write_story — the tool does not write, it returns guidance material. It never names siblings like start_story, submit_story, or review_story, so the agent must infer the boundary itself.

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

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

Usage is only implied: the agent can guess this belongs before drafting a story, but there is no explicit 'use this when...' statement, no mention of what to do after (draft, review, submit), and no guidance on choosing genre or length for a given situation.

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