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

With no annotations, the description carries the full burden and does add real behavioral context: 'free and instant' discloses cost/latency, 'a hidden prop leaves the mascot as it was' signals the change is non-destructive and reversible, and 'exports and embeds follow' discloses propagation to downstream artifacts. It does not cover error cases or whether a nonexistent prop name is silently ignored.

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?

Compact and front-loaded: the action and resource come first, followed by the example, then the cost and side-effect facts. Every clause carries information, with only mild density cost from packing several behaviors into one sentence.

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 a nested object parameter, no annotations, and no output schema, the description covers the essential ground: what props are, the input shape, the cost, and the effect on mascot state and exports. The main residual gap is clarifying the required mascot id/name argument.

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

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

Schema description coverage is 0%, so the description must compensate, and it partly does by clarifying that props is a map of prop identifier to boolean, with the example { mug: false, crown: true }. However, 'by id or name' is ambiguous about whether it applies to the mascot identifier or the prop keys, and the required top-level 'id' parameter is never explicitly explained.

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 pair (show/hide) and resource (the mascot's props), with a parenthetical defining what props are ('things it holds or wears') and a concrete example. It is distinguishable from most siblings, though it never explicitly contrasts with add_prop, the tool that adds new props.

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 points to get_mascot for discovering props and shows the expected input shape, which implies the workflow, but it gives no explicit when-to-use vs when-not guidance and does not name add_prop as the alternative for introducing props the mascot doesn't already have.

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