compare_decks

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

With no annotations at all, the description carries the full burden and does so: it declares read-only semantics, the matching key (keyword + id, not order), the normalisation rules (case, comma vs fixed format, 1.0e3 == 1000, *PARAMETER values), the complete status vocabulary including default-vs-explicit and known_workbench_default, and the 300-row cap with differences-first ordering and a `truncated` flag. These are exactly the non-obvious behaviors that would otherwise cause misinterpretation of results.

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 and matching rules are front-loaded, but the middle is a dense parenthetical wall of card names (MAT_JOHNSON_COOK, CONTROL_TERMINATION/SPH/HOURGLASS/TIMESTEP/CONTACT/ENERGY, SECTION_SOLID/SPH/SHELL...) that conveys coverage but is expensive to read. The argument notes are jammed into a trailing run-on rather than broken out per parameter.

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 4-parameter, no-annotation tool this is close to complete: it covers what is compared, how rows are matched and normalised, what the statuses mean, and how truncation is signalled (return values themselves are covered by the output schema). Minor gaps remain around file-precondition failures and whether units/format differences on the reference side are tolerated.

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 largely does: `cards` is explained as keyword prefixes with "default all", and `candidate_unit_scale` gets a precise, non-obvious definition ("how many candidate units one reference unit is, per base quantity") plus which quantities it converts and that absent means raw comparison. Only `reference_path`/`candidate_path` are left self-explanatory, which is acceptable.

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?

Opens with a specific verb and resource ("Read-only field-by-field comparison of two keyword decks") and immediately contrasts the two sides being compared (standalone reference vs. a Workbench-authored deck). This is clearly distinguishable from siblings like audit_deck or scan_keyword_file, which inspect a single deck.

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 "for example a standalone reference against the deck Workbench wrote" clause gives a concrete usage context, and the reference to audit_deck for known_workbench_default gives a hint of the companion tool. However, there is no explicit "use this instead of X when Y" or any exclusion, so an agent must infer that single-deck checks belong to audit_deck.

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