remove_location

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context the annotations can't: exactly what is destroyed (everything inside, including Packet Tracer's power units in racks), and the critical fact that the edit is written as bytes into a temporary copy that is discarded unless save_network is called. That persistence caveat is the kind of behavioral disclosure that prevents silent data loss.

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?

Three front-loaded sentences with no filler: the destructive scope comes first, the precondition second, and the persistence requirement last. Every sentence carries information an agent needs to act correctly.

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, so return values need no explanation. Between the destructive scope, the move-out precondition, and the temp-copy/save requirement, the description covers everything needed to call this mutation safely and correctly.

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 coverage is 100% and the single 'path' parameter is fully documented in the schema, including the list_locations reference and the 'everything inside goes too' warning. The description's restatement of the deletable object types adds little 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?

States a specific verb ('Delete') and precise resources (city, building, wiring closet, rack) with the crucial scope qualifier 'with everything inside it.' An agent can distinguish this from siblings like remove_device and remove_note without opening the 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?

Explicit precondition ('Devices must be moved out first (move_to_location)') routes the agent to the correct alternative tool when the condition isn't met, and it names save_network + a path as the required follow-up to persist the change. Both when-to-use and the alternative path are spelled out.

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