tokyo_play

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

With no annotations, the description carries the full burden but does disclose real behavioral facts: the action requires a signed-in session, body is a small JSON object, and some actions may respond 'closed' rather than succeed. It does not characterize the mutating paths (gang/create, gang/leave, uc/siege, uc/raid) as state-changing or irreversible, nor describe failure/error behavior beyond the Season 2 note.

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 with the primary contract front-loaded, which is efficient. However, the 19-value path enumeration is copied verbatim from the schema enum and adds no information, while the truly novel content (body shapes) is compressed into a single parenthetical covering only three paths.

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 generic dispatcher with 19 routes, an untyped body parameter, and no output schema, the description covers the essentials: what to pass, examples, and a hint to read the response message. It is not complete because most body schemas remain unstated and the return shape is only gestured at ('read the answer's message') rather than described, though the absence of an output schema is a mitigating factor.

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% and 'body' is an untyped free-form object, so the description must compensate — and it does add genuinely new information by mapping three paths to their body keys. But three examples cover only 19 paths, leaving the shape of most bodies (e.g. uc/siege, uc/auction, uc/table) undocumented, and the path list merely duplicates the schema enum.

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 concrete verb and scope ('Call a signed-in game action') and enumerates the exact set of callable paths, so an agent knows precisely what this tool does. It falls short of a 5 because it never separates itself from siblings like tokyo_read, which plausibly overlap with read-flavored paths such as 'me', 'uc/mine', and 'uc/scan/me'.

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 per-path body examples (gang/create {name}, gang/join {code}, daily {district}) and a useful operational note that chip games may answer 'closed' until Season 2 districts open. However, it never says when to prefer this tool over tokyo_read, nor explicitly that tokyo_sign_in must precede it, so routing guidance is only implied by the phrase 'signed-in game action'.

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