Weather With Attitude

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

Annotations only declare readOnly/idempotent/openWorld, so the description carries real weight and does: it discloses the return contents (current conditions in Celsius, 3-hour steps for the next few hours, share-card link, website link), the MCP Apps card behavior, and the notable edge case that severe conditions are reported plainly without a joke. That edge-case disclosure is behavior an agent could not infer from annotations or schema.

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

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

Front-loaded with the trigger, then returns, then exclusions — a sensible order. The attitude-level sentence largely duplicates the enum descriptions in the schema, which is the one place the text does not fully earn its space.

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 must explain return values and does so concretely (units, forecast granularity, links, card rendering). Combined with the safety exclusions, an agent has everything needed to call it and set expectations correctly.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the city format and the enum meanings. The description restates the attitude levels but adds no syntax, defaulting, or format detail 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 (looks up current temperature and conditions for a city and returns a joke) and clearly frames it as a novelty forecast, distinguishing it from any serious weather tool. The name-plus-description pair leaves no ambiguity about what the tool produces.

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?

Opens with an explicit trigger ("Use this when someone wants a funny or rude weather forecast") and closes with explicit exclusions ("Do not use it for serious weather needs such as safety decisions, severe-weather alerts... or multi-day forecasts"), each backed by a reason. This is the when/when-not pattern at full strength.

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, so the safety profile is covered. The description contributes the useful fact that this is a backward-compatibility alias, but it does not say what the call actually does to game state (ending the round, revealing the answer) or what a caller receives back – meaningful for a tool with 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?

A single sentence with zero waste, and the operative constraint ('never by the model') is front-loaded. Nothing to trim.

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 deprecated alias, the essential thing an agent needs – do not call this – is stated, and annotations cover the safety profile. The one gap is that it does not name the replacement tool explicitly, so an agent must infer 'weather_word_puzzle_give_up' from the sibling list.

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 all five parameters (puzzle_number, time_zone, utc_offset_minutes, previous_guesses, conversation_id) are already documented in the schema. The description adds no parameter-level detail, 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?

Together with the title, the description makes clear this is the give-up/show-the-word puzzle step, and adds that 'give_up' is a legacy alias retained for backward compatibility. The functional role (a renamed puzzle step) is specific, though the description itself never restates the action and relies on the title to convey it.

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?

'Used only by the puzzle card, never by the model' is an explicit, unambiguous when-not-to-use rule plus the actor that does use it. An agent knows immediately not to route to this tool, and the sibling 'weather_word_puzzle_give_up' makes the replacement obvious.

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 disclose that this is a non-readonly, non-idempotent, non-destructive, closed-world write. The description adds useful privacy context: it is anonymous and excludes location, prompt, city text, roast text, and account identifiers. It does not detail data retention or full side effects, but the annotation coverage lowers that burden.

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 wasted text. The card-only usage constraint is front-loaded and the anonymity detail follows immediately, making the description 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 six-parameter write tool with no schema parameter descriptions and no output schema, the definition explains purpose and privacy but not how to populate the required `tool` field or the optional event metadata. It is sufficient to tell the model not to call it, but not sufficient to invoke it correctly from the definition alone.

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% across six parameters. The description only loosely maps to the event and link concepts, and does not explain the required `tool` parameter or the meanings of `puzzle_number`, `attitude_level`, or `conversation_id`, leaving most invocation semantics to the raw enum names.

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: record that the connector card was shown or a link was opened. It also distinguishes the tool from sibling model-facing tools by saying it is used only by the connector's card, never by the model.

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 explicit when-to-use condition (card shown or link opened) and an explicit when-not-to-use condition (never by the model). This is exactly the routing guidance an agent needs to avoid selecting it in normal model workflows.

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 already cover safety (readOnly, idempotent, non-destructive), and the description adds useful lifecycle context: it is an earlier name retained so cards opened before the rename still work. This informs compatibility behavior beyond the annotations without contradicting them.

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

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

A single sentence with no wasted language, and the most important constraint ('never by the model') is 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?

Given full schema documentation, annotations declaring it safe/idempotent, and no output schema, the description provides the key context an agent needs: this is a legacy card-only path. It could be slightly more complete by naming the current replacement, but it is nearly sufficient.

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

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

Schema description coverage is 100%, so the three optional parameters are already fully documented in the schema. The description adds no parameter-level detail, which is acceptable but does not exceed the 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 identifies this as a legacy alias for a puzzle step, but does not itself state the action (starting today's puzzle) or name the current replacement. The title and tool name carry most of the purpose; the description mainly adds deprecation 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?

It gives a clear exclusion: 'Used only by the puzzle card, never by the model,' which directly guides the agent away from invoking it. It explains the compatibility context but does not explicitly name the current sibling tool to use 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 already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine context the annotations cannot express: this is a legacy alias retained for cards opened before a rename. It says nothing, however, about what a call returns or how wrong guesses behave, and with no output schema that silence matters.

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 most decision-relevant clause ('never by the model') front-loaded. No padding or repetition. It is short to the point of omitting useful detail, but nothing in it is wasted.

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

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

For a 6-parameter tool with no output schema, the definition covers only the compatibility status; it never explains what comes back (correct/incorrect, remaining attempts, updated board state). Since the model is told not to use it, the gap is tolerable, but an agent that does encounter it lacks enough to interpret results.

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 including guess, puzzle_number, time_zone, previous_guesses and conversation_id is already documented in the schema. The description adds no parameter meaning whatsoever, which is acceptable here but earns only the 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 identifies the tool as an earlier name for 'this puzzle step' kept for backward compatibility, which implies it duplicates the guess-checking sibling, but it never states the function directly (submit a word guess and get correctness feedback). The title 'Check a guess' carries most of the actual purpose, so the description alone is vague on what a call does.

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?

Strong, explicit exclusion: 'Used only by the puzzle card, never by the model.' That is a clear when-not-to-use rule an agent can act on immediately. It falls short of a 5 because it never names the replacement it should call instead (weather_word_puzzle_guess), leaving the routing implicit.

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?

Adds real context beyond the annotations: the call is scored as a loss and returns the answer plus a spoiler-free share grid. However, it leaves the state semantics ambiguous — 'ends the game as a loss' reads like a mutation while readOnlyHint=true and idempotentHint=true declare no side effects, and the description never clarifies whether giving up is final, whether it works after the puzzle is already solved, or what happens on a repeat call.

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

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

Three short sentences, front-loaded with the gating condition, then outcome, then required inputs. Nothing is padded or repeated.

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

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

There is no output schema, and the description does compensate by naming the three things returned (answer, board, share grid). Fully parameterised schema reduces the burden, but error conditions (invalid puzzle_number, giving up before the first guess or after solving) are unaddressed.

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 explains all five parameters in detail. The description's 'send the puzzle number and every guess made so far' largely restates puzzle_number and previous_guesses, and adds no syntax, ordering, or edge-case guidance beyond what the schema provides; 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 ('give up on the daily word puzzle'), and discloses the outcome (recorded as a loss) plus the return payload (answer, board, share grid). It is clear what the tool does, but it never differentiates itself from the sibling simply named 'give_up', which an agent could plausibly confuse it with.

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 constrains invocation: 'Use this only when the player asks to give up', which tells the agent not to call it unprompted. It does not name the alternative (weather_word_puzzle_guess / submit_guess) for continuing play, so the routing is one-sided rather than 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 already declare read-only, idempotent, non-destructive, but the description adds beyond them: statelessness ('nothing is stored on the server'), per-letter result marking, invalid guess handling with a reason, and the fact the answer is revealed only on a correct guess or the sixth miss. That is substantive behavioral context an agent cannot infer from 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?

Five sentences, front-loaded with the when-to-use, then return shape, then validation, then end conditions. Every sentence carries information; it is slightly long but no sentence is 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?

No output schema exists, so the description must describe returns — and it does, covering the letter-by-letter marking, the short comment, and the answer-reveal condition. For a stateless, idempotent check call, an agent has everything needed to invoke and interpret it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: it says to send the puzzle number, every earlier guess in order, and the new guess — clarifying that previous_guesses, though optional in schema, is operationally required for correct marking. The letters-only/same-length constraint also reinforces the guess format.

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

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

States a specific verb and resource ('check each word the player guesses in the daily word puzzle') and anchors it to the start tool, so an agent can distinguish it from weather_word_puzzle_start and weather_word_puzzle_give_up 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?

Explicitly says to use it for each guess in a game begun with weather_word_puzzle_start, and the invalid-guess clause ('does not count') prevents an agent from aborting on a rejected word. Implicit sibling boundaries (start vs give up) are strongly implied by the referenced flow.

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, and the description adds real context beyond them: it returns puzzle number, word length and an empty board, and explicitly never the answer. The UTC-vs-local-date fallback behavior is also disclosed. Return payload shape is described but not, e.g., what happens on replay of the same day.

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 sentences, front-loaded with the usage trigger and ending with the next-step hand-off; nothing is wasted. The middle sentence is long but carries the rules, return contract and time-zone caveat, so the density is justified rather than bloated.

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 the work of explaining what comes back (puzzle number, length, empty board, never the answer), and all three parameters are contextualized. The one omission is disambiguation from the similarly named start_daily_puzzle sibling in a crowded namespace.

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 decision-level meaning: pass time_zone when known so the puzzle follows the player's local date, otherwise it follows UTC. That explains the interaction between time_zone and utc_offset_minutes that the schema documents only in isolation.

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 ('start the daily word puzzle' in Weather With Attitude) and describes what the puzzle actually is: guess a hidden cheeky word in six tries. It also names the follow-on sibling weather_word_puzzle_guess, so the agent can place it in the workflow 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?

'Use this when someone wants to play the daily word puzzle' gives an explicit trigger, and the closing sentence routes subsequent guesses to weather_word_puzzle_guess. It does not, however, distinguish itself from the start_daily_puzzle sibling, which an agent could plausibly confuse with this tool.

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