map_save_as

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

The annotations already disclose that this is a non-readonly, non-idempotent, non-destructive, closed-world operation. The description adds that the snapshot is immutable and names revision_saved and conditional clean_ack, but it does not explain what makes clean_ack conditional, what happens on validation or revision mismatch, or whether publishing can be undone.

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 definition is a single front-loaded sentence with no filler, and it puts the main operation before the return information. It is slightly too compressed because 'Validate reload' is unclear, which keeps it from being a 5.

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 four-parameter mutation with concurrency-sensitive inputs and no output schema, the description is too thin. It should explain expected_revision conflict behavior, the role of map_epoch and request_id, and when clean_ack is returned.

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 0%, and the description mentions none of the four required parameters. slug, map_epoch, expected_revision, and request_id are left entirely unexplained; revision_saved is an output field, not a substitute for explaining expected_revision.

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 says it publishes an immutable map snapshot and names two return fields, which gives some specific purpose. However, the phrase 'Validate reload' is ambiguous and it never clarifies what is being saved 'as' (for example, under a slug) or how it differs from siblings such as map_new or map_open.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. An agent cannot tell from this description when map_save_as should be chosen over map_new, map_open, or other map operations.

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