Activate or deactivate a split rule

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the mutation profile is covered structurally. The description adds real value beyond that: it warns that live mode moves real money or redirects payout destinations, and that the effect is irreversible for already-created payments — exactly the operational context an agent needs before invoking a destructive toggle.

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 opening sentence is duplicated word-for-word, which is pure waste and pushes the genuinely useful warning further down. The remaining two sentences are well-formed and front-load the consequence before the caution, but the redundancy and the joint title/description overlap weaken structure.

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 two-parameter toggle with no output schema, the description covers the key concerns: what changes, the effect on existing payments, live-mode risk, and a confirmation requirement. Only smaller gaps remain, such as whether reactivation restores prior behavior or whether any response payload should be expected.

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% and both parameters are documented, with the 'active' parameter description nearly duplicating the prose sentence. The description adds no new syntax, format, or edge-case meaning for 'id' (such as whether a deactivated rule can be re-fetched or reactivated) beyond what the schema states, so the baseline 3 applies.

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?

States a specific verb pair and resource ('Activate or deactivate a split rule'), which is unambiguous and clearly distinct from siblings like create_split_rule, get_split_rule, and list_split_rules. It loses a point only because the same sentence is repeated verbatim rather than expanding on scope or audience.

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 a clear usage effect (deactivated rules can't be used for new payments while existing payments keep their frozen split) and a pre-call caution about confirming amount and destination with the user. However, it never explicitly frames this against alternatives — e.g., it does not say to use get_split_rule to inspect current state first, or create_split_rule to make a new one — so the routing guidance is implied rather than stated.

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