adjust_rack_macro_count

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

Annotations already cover the safety profile (destructive, non-idempotent, open-world), so the bar is lower. The description adds a real behavioral constraint that annotations cannot express: the remove action is blocked while macro mappings exist because the mapping target is not exposed, and it reports the observed count after acting.

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?

Two tight sentences that front-load the capability and then the removal guard. Slightly dense prose ('one native add/remove macro action on an exact rack') costs it a point, but nothing is wasted.

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 mutating, non-idempotent tool with no output schema, the description covers the action scope, the destructive-path refusal, and the report-back behavior, with annotations carrying safety. Remaining gaps (pagination/return shape) are minor since it explicitly says it reports the observed count.

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 dryRun/confirmationToken/planHash/expectedStateVersion are all already documented in the schema. The description adds the notion of 'exact rack' and the plan-vs-invoke duality but no syntax or format detail beyond the schema, so the 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?

Names a specific verb pair (plan/add/remove) plus the exact resource (one native macro action on an exact rack) and states the outcome (report the observed count). This is clearly separable from siblings like map_rack_macro_to_parameter and rename_rack_macro without opening either 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?

Gives a concrete precondition for the destructive path: removal is refused while any macro mapping exists, with the reason (Live does not expose the affected mapping target). It does not explicitly route the agent away from sibling tools, but the when-to-use context is clear.

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