Edit virtual tour

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

Annotations already declare destructiveHint=true and openWorldHint=true; the description adds real value on top by stating the operation is free and instant and that the public link reflects the change immediately. It stops short of calling out irreversibility or confirmation requirements for the destructive removals, which is what a 5 would need.

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?

Front-loads the core purpose, then lists the supported mutations, then gives the operational facts and the helper-tool pointer in two short sentences. Dense but every clause maps to a distinct capability; only the parenthetical about the first scene borders on restating the schema.

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 10-parameter destructive mutation tool with no output schema, the description covers what changes, the side effects on the public link, and where to source sceneIds. It omits failure behavior and whether removed links/photos are recoverable, which are the remaining gaps an agent would want.

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. The description groups operations and maps them to parameters (rename → name/sceneNames, reorder → sceneOrder, remove → removeScenes, links → links), but most of that detail is already in the schema and it adds no extra syntax or constraint information.

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 (Change/edit in place) and resource (virtual tour), then enumerates the concrete mutations supported: rename tour/rooms, reorder, remove rooms, replace links, restyle navigation. It is clearly distinguishable from sibling tools like pedra_create_virtual_tour and pedra_add_virtual_tour_scenes because it operates on a finished tour rather than building one.

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?

"Change a finished virtual tour in place" scopes usage to an existing, completed tour, and it explicitly routes the agent to pedra_get_virtual_tour for sceneIds. It does not state exclusions (e.g. don't use for adding scenes – that's pedra_add_virtual_tour_scenes), so it falls short of full when/when-not guidance.

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