firestarter_set_auto_approve_limit

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

Annotations declare idempotentHint=true, destructiveHint=true, readOnlyHint=false, and the description aligns with these: it is a state-changing write (supports destructiveHint), and setting the same limit again would be idempotent (supports idempotentHint). The description adds critical safety context beyond annotations: orders at the limit are paid without confirmation, the stored value is exact/precise, and the success signal is the response echo of the stored setting. It does not spell out every effect (e.g., whether disabling is reversible immediately), but it discloses the most important safety-critical behavior.

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 prose is dense but organized: identity/scope first, operational semantics second, parameter guidance third, safety caveat before the read-sibling pointer. It is longer than strictly required, but nearly every sentence contributes functional information. The trailing sentence about the read sibling is brief and relevant. No clutter or repetition.

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?

The description is complete for a mutation tool with no output schema. It explains the safety profile (orders auto-approve, exact value is safety-critical), the persistence scope (account-level, across surfaces), the two modes, the maximum limit, and the recommended read route. An agent can decide correctly whether to call this tool and what to pass without requesting additional info.

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 100%, so the baseline is 3 even with no additional parameter details. The description nevertheless adds useful framing—context that orders at or below the limit pay without manual confirmation, and the safety-critical precision of the stored value—supported by examples like 50 and 0. It does not add brand-new param syntax beyond the schema, but it does explain the semantics well; baseline 3 is appropriate.

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 opens with a specific verb ('Set or disable') and a precise resource: the buyer's persistent, account-level auto-approval limit. It clearly distinguishes itself from the sibling firestarter_auto_approve_limit, noting that this tool sets while the sibling reads. The scope ('account-level', 'across all surfaces') removes ambiguity, and the maximum-limit and 0-value semantics are explicit.

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 description explicitly states when to use the tool ('Set or disable the auto-approval limit'), how to choose between the two mutually exclusive parameters (set_limit_usd OR disable=true), and the read alternative: 'Use firestarter_auto_approve_limit to read the current value without changing it.' This covers the key decision an agent faces—whether to modify or only query—and leaves no room for guessing.

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