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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description goes further with real behavioral context the annotations cannot supply: it returns mapData:null when a map has never been saved, contentVersion is dependency-sensitive and must be preserved in the map lock entry, and rendering/area settings are advisory-only (materials, never geometry or physics).

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 description is a single ~250-word paragraph of densely packed data-model prose with no structure. It is not front-loaded: the operationally critical fact that mapData is null for never-saved maps is buried in the final clause, and much of the text is format reference rather than selection guidance.

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?

With no output schema, the description carries the burden of explaining the returned payload and does so substantially: materialRendering v1, materialArea v1, terrain materialGrid/ramps, layer ordering, gameplayId and custom fields. This is genuinely needed for an agent to interpret the response, though coverage of revision and placement/layer enumeration is still partial.

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?

There is a single parameter (mapId) and schema description coverage is 100%, so the schema already carries the parameter's meaning. The description adds nothing about how to obtain or format mapId, so the baseline of 3 applies.

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 opening sentence states a specific resource and scope: a map row plus saved level data, revision and a dependency-sensitive contentVersion for plan_sync. An agent can tell this is the read-side input to the plan_sync/import workflow. It does not, however, distinguish itself from close siblings such as get_map_draft, map_authoring_context or map_workbench_context.

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?

The only usage signal is embedded procedural advice ('Preserve the returned contentVersion in the map lock entry after a successful import'), which describes post-processing rather than when to call this tool. There is no statement of when to prefer get_map over get_map_draft, list_maps, or map_authoring_context, and no exclusions.

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