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

With no annotations provided, the description must carry the full burden. It does disclose that shared edit mode auto-saves, a useful side-effect clue. However, it doesn't state whether the operation is destructive (does it overwrite existing roads?), what happens on failure, or whether it requires a loaded document — gaps for a mutation tool with zero annotations.

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 sentences, zero filler. It front-loads the core action ('Replace roads via friendly markup') then adds the format reference and auto-save side effect. Each sentence earns its place, though the description is brief enough that more useful guidance could be added without harming conciseness.

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 mutation tool (apply/replace) with no annotations and no output schema, this description is thin. It doesn't explain what the markup format supports, whether edits are destructive, what the return/response is, or how it relates to workflows involving create_shared/open_shared/create_new/discard. The auto-save note is helpful but incomplete for a state-changing tool.

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% with a single 'markup' parameter documented as 'Friendly roadflow markup text'. The description adds the key clarification that the markup matches the editor panel's format, which meaningfully augments the bare 'friendly roadflow markup text' schema description. For a single simple param, this is adequate.

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 states 'Replace roads via friendly markup' which is a clear verb+resource, distinguishing it from roadflow_apply_json (the JSON alternative). However, it doesn't detail what kinds of markup operations are supported (add, remove, modify roads) beyond 'replace', leaving scope ambiguous compared to the sibling apply_json tool.

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?

'Same as the editor panel' gives helpful context that markup format matches the UI, and mentions shared edit mode auto-saves. However, it doesn't explicitly say when to use this tool vs roadflow_apply_json, when not to use it, or mention shared mode vs the open_shared/create_shared distinction which sibling names suggest.

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