clone_deck

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

With zero annotations, the description carries the full behavioral burden and does substantial work: it discloses non-destructive writes ('Writes a NEW deck'), reporting behavior ('reports per-op substitution counts'), re-validation ('re-validates'), and domain nuance ('last control in SCHEDULE wins'). It leaves failure behavior on validation errors unstated, but the core safety profile is well covered.

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?

Roughly 40 words across three sentences, front-loaded with the root action and override scope. Every sentence carries distinct information — purpose, behavioral guarantees, and an idiomatic example — with zero filler or repetition of schema content.

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?

An output schema exists (lightening the return-value burden) and the description covers new-deck semantics, per-op counts, and re-validation. But the overrides parameter — the core input beyond deck_path — is structurally undocumented, and flatten_includes is never mentioned; at 0% schema coverage this is a significant gap for actually constructing a valid call.

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 every parameter needed description-level meaning. The description maps to the overrides param by naming its four op types and implies output_path behavior via 'Writes a NEW deck', but it never explains the shape of overrides entries (fields each op requires), nor flatten_includes, validate, or output_path semantics. Partial compensation, not full.

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?

Description states a specific verb+resource: 'Clone a deck' with concrete override mechanisms (append_before_end / replace_regex / set_title / insert_after_keyword). It self-differentiates from read-only siblings like validate_deck, summarize_deck, and deck_grep by asserting it 'Writes a NEW 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?

Provides concrete operational guidance: 'Idiomatic rate/BHP change: append a new WCONPROD/WCONINJE via append_before_end (last control in SCHEDULE wins)'. However, it never names alternatives or states when NOT to use this tool versus siblings such as validate_deck or pack_deck, leaving exclusions implicit.

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