Author a fight in one call

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

Annotations declare idempotentHint and destructiveHint; the description reinforces idempotency by name ('leaves one foe, not one foe per run') and adds real behavioral detail beyond the annotations — names resolved against project tables, missing rows refused, and the specific failure mode where an action naming a skill with no Skills row 'throws on the turn the foe decides to act.' It does not explicitly warn about the destructive overwrite of existing rows, so not a 5.

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 purpose is front-loaded, but the prose is dense and parenthetical, with long run-on sentences carrying embedded code enumerations. Each clause is informative, but the trait-code list and the item-effect aside make it heavier than needed for a description whose job is selection and invocation.

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 nested tool with no output schema, the description covers the two-row output scope, the tricky encodings, resolution/refusal behavior, and idempotency, and briefly notes output comes back 'in words.' Combined with a fairly rich schema, this is nearly complete, with the main gap being the destructive-overwrite implications of rewriting an existing row.

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

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

With schema coverage at only 25%, the description compensates by documenting the failure-prone encodings the schema doesn't: the drop shape `{kind, dataId, denominator}` and its denominator semantics, the trait `{code, dataId, value}` codes (11/12/14/21/22/31/32/63), and the value-vs-value1/value2 distinction. This is meaningful semantics beyond the schema, though it references a 'trait' shape not obviously present as a top-level property.

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+resource ('Author a fight') and precisely what gets created: 'Both rows a battle needs — the Enemies row and the Troops row that holds it — from one ask.' It explicitly distinguishes itself from the sibling create_database_entry, which 'has to be handed the whole thing.' An agent can tell what this tool produces versus alternatives without opening any 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?

It names the alternative (create_database_entry) and the condition selecting this tool over it, and hints at the zone/region use case ('the region that rolls it if you want it met by walking'). It also frames the idempotency benefit for 'a build script that runs twice.' It stops short of explicit when-not-to-use exclusions, so a 4 rather than 5.

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