Moving Polygons

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

Annotations already declare non-readOnly, non-idempotent, non-destructive, so the safety profile is covered. The description adds two genuine facts not in the annotations: the map is created as a private draft (not published) and the payload limit is about 1 MB — useful failure-mode context, but nothing about permissions, what happens on repeat calls, or the response.

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?

One sentence, front-loaded with the verb and the outcome state ('private draft'), with the input source and size caveat trailing. No filler.

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?

Adequate for a single-parameter creation tool with annotations, but there is no output schema and the description never says what comes back (a map ID or URL) or whether the created draft is immediately retrievable via get_map. The size limit is also vague ('about 1 MB').

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?

Only one parameter and schema coverage is 100%, so the schema already explains that 'map' is the Moving Polygons import format as object or string. The description's only added semantics is the ~1 MB size ceiling, which is a real constraint but marginal against a fully documented schema.

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?

Specific verb and resource ('Create a new ... map') with two differentiating qualifiers: the resulting object is a private draft, and the input is an import JSON payload. It is separable from siblings like replace_map_content and publish_map, though it never names them.

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 'from an import JSON' phrasing implies the precondition for calling it, and the size limit hints at when it will fail, but there is no explicit guidance on when to use this versus replace_map_content or publish_map, and no mention of fetching the format via get_import_format.

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

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

The annotations declare readOnlyHint=true, but the description explicitly says the tool creates a new draft map or overwrites an existing map's content. That is a direct contradiction of the read-only annotation, so behavioral transparency scores 1 despite the useful link-validity and size details.

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 front-loaded with the key resource and constraints and uses only three sentences. The final sentence about curl output is slightly vague, but the overall structure is efficient and easy to scan.

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 two-parameter tool, the description covers important constraints like link lifetime, file size, curl usage, and the two modes. However, with no output schema it only vaguely says the curl output reports the result, and it does not clarify permissions or the returned link format.

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%, and the enum already documents create versus replace. The description adds only a brief restatement of mode replace overwriting existing content, so the schema is doing the primary work.

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 clearly states the specific resource: a one-off upload link for a map JSON file, with validity and size constraints. It distinguishes the operation from sibling map tools by framing it as an upload link rather than direct map creation, though it does not explicitly name the nearby alternatives.

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?

Usage is implied through the curl upload scenario and the mode replace behavior, but there is no explicit when-to-use guidance versus create_map or replace_map_content. It also does not state when not to use this tool or what the prerequisites are.

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

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

Annotations already flag non-read-only, non-idempotent and destructive behavior; the description usefully adds that it validates the map, reports missing parts or JSON errors, and keeps a backup when replacing content. This meaningfully supplements the safety profile, though it does not discuss auth/rate limits or success return behavior.

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?

A single dense sentence, front-loaded with the action and outcome; the parenthetical efficiently conveys replacement and backup behavior. Every clause carries operational information with no filler.

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 with no output schema, it explains validation and failure reporting as well as backup behavior, while annotations cover the side-effect profile. It omits prerequisites such as start_map_upload/upload_map_part and the success return shape, but provides enough to call it 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 50%: parts has a range and description, while uploadId is undocumented. The description clarifies that parts are joined from 1 through the supplied count, adding semantics beyond 'how many parts were sent,' but uploadId remains unexplained.

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 (finish/joins) and resource (chunked map upload) and distinguishes the finalization step from siblings such as start_map_upload and upload_map_part by describing joining parts and creating or replacing a map.

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 chunked-upload context implies it should be called after parts are uploaded, but it never explicitly says so, nor when the create-draft vs replace-content path applies or why one would choose this over replace_map_content. Usage is inferable but not guided.

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

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

The readOnlyHint=true annotation is consistent with the description, which describes a passive fetch. Beyond the annotation, the description discloses the return payload (handle, plan, remaining map creations), which is valuable since there is no output schema. It doesn't mention auth or error behavior, but the core behavior is conveyed.

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?

A single compact sentence with no filler, and the most important scope qualifier ('signed-in user's') is front-loaded. It reads as a fragment rather than stating an action, which slightly weakens the opening.

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 no-parameter read tool with annotations covering safety, the definition is nearly sufficient, and it helpfully outlines the return fields in the absence of an output schema. Additional detail on what 'plan' means or quota semantics would make it fully complete.

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 are zero parameters, so the baseline is 4. The description reinforces this by tying the tool to the 'signed-in user', making clear no identifier is required.

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?

It names the specific resource (the signed-in user's account) and enumerates what's returned: public handle, plan, and remaining map quota. It lacks an explicit verb like 'retrieve', but the resource and scope are unmistakable, and 'signed-in user's' separates it from get_public_map or get_map.

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 phrase 'signed-in user's' implies it needs no identifier and applies only to the caller's own account, which is a useful usage cue. However, it never states when to prefer this over get_public_map, get_map, or list_maps, nor any preconditions such as authentication failure behavior.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds useful context about what the returned JSON format contains, though it does not describe the full response shape or any other behavioral constraints.

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 concise sentence fragment with no wasted words and the key information is front-loaded. It could be slightly more explicit as a sentence, but it is appropriately sized for a zero-parameter format lookup.

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 must carry responsibility for explaining the return value. It lists the main components of the format, which is helpful, but does not provide enough detail to fully understand the returned JSON structure.

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?

The tool takes zero parameters, so parameter semantics are inherently limited and the baseline is 4. The description does not need to compensate for any parameter documentation.

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 name/title plus description make clear this tool returns the JSON import format for maps, and the listed components (layers, timed polygon keyframes, point markers, style) are specific. It does not explicitly differentiate from siblings such as create_map or replace_map_content, so it falls short of a 5.

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 description gives no guidance on when to use this tool versus alternatives, such as whether it should be called before create_map or replace_map_content. It implies a read-only lookup but states no usage context or exclusions.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the payload includes a downloadable link with a 15-minute expiry and warns the JSON can be several MB, which matters for how an agent handles the result. It stops short of saying whether the link is single-use or what happens on expiry.

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?

One sentence, front-loaded with what is returned and followed by the caveat about the download link. Nothing is wasted, though the nested clause in the middle makes it slightly dense.

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 must describe the return value and does so adequately: a summary of layers, keyframe dates and markers plus an expiring download link for full JSON. An agent knows what it gets and roughly what to expect size-wise; only link lifecycle details are missing.

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% for the single mapId parameter, so the schema carries the parameter burden. The description never mentions mapId or its format, adding nothing on parameters — the baseline 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 description names a specific verb+resource ('summary of one of the user's maps') and enumerates the returned fields (layers, keyframe dates, markers), which tells an agent this is a single-map fetch. It does not explicitly contrast with siblings like list_maps, get_public_map, or search_maps, so differentiation is left to inference.

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?

Usage is only implied: fetch a single map by id, as opposed to listing/searching. There is no explicit statement of when to prefer this over get_public_map or search_maps, nor any prerequisites such as ownership or auth.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description earns credit by being the sole disclosure of the return payload (Markdown body, keyframe timeline, layers, events, iframe code), standing in for the missing output schema. It does not mention whether unpublished/private maps are rejected or what an invalid URL/handle produces.

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?

A single front-loaded sentence: return contents first, invocation second. Every clause carries information — the payload list and the two calling modes — with no filler.

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 supplies the return shape thoroughly, which is the main burden here. Gaps are minor: no failure behavior, no statement of what an unpublished or nonexistent map returns, and no confirmation that zero arguments is not a valid call despite required params being empty.

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 only 33% — url has an example, slug and username have nothing. The description partially compensates by presenting two input modes (URL alone, or handle+slug), but it never states that 'handle' maps to the `username` field, nor whether both of those are jointly required, leaving ambiguity at the exact point the schema is weakest.

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?

Names a specific verb and resource ('One published map as Markdown') and enumerates exactly what comes back (description, sources, keyframe timeline, layers, events, iframe embed code). The word 'published' is the only signal separating it from the sibling get_map, which is a reasonable but unstated distinction.

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?

'Pass its URL, or the handle and slug' tells the agent how to call it but not when to prefer it over get_map, list_maps, or search_maps. Usage is implied by 'published map' rather than stated, and there are no exclusions or prerequisites.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already covered; the description adds real value beyond that by disclosing scope (only the user's maps), ordering (most recently changed first), and the return payload (ids and links). It stops short of saying how the list is truncated or whether results are paginated past the limit.

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?

A single compact sentence that front-loads scope and ordering, then the return shape. Nothing is redundant and nothing could be cut without losing information.

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 simple two-optional-parameter read tool with no output schema, the description covers scope, ordering, and returned fields, which compensates for the missing output schema. The remaining gap is pagination/truncation behavior relative to limit.

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 both the limit default and the search filter semantics are already documented in the schema. The description adds no meaning beyond that, so the baseline 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 description states the resource and its scope precisely: the user's own maps, sorted most-recently-changed first, returning ids and links. That implicitly separates it from get_public_map (other people's maps) and get_map (a single map). It does not explicitly name a sibling to disambiguate against, notably search_maps, which leaves one inference to the agent.

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 when-to-use or when-not-to-use guidance, and no mention of alternatives. The presence of a sibling named search_maps plus a 'search' parameter on this tool makes the routing decision genuinely ambiguous, and the description does nothing to resolve it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the meaningful consequence that anyone can view the map and the resulting URL shape, but omits whether the change is reversible, whether it requires ownership, and what happens if the map is already public.

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?

A single front-loaded sentence with the verb first, followed by the resulting URL and its visibility consequence. No wasted words.

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 one-parameter mutation tool with no output schema, the description explains the resulting state but leaves gaps on permissions, idempotency/error behavior, and the relationship to unpublish_map, which matters for a visibility-changing operation.

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 single parameter mapId has no description in the schema. The description never clarifies whether mapId is an internal ID versus the handle/slug shown in the public URL, so it fails to compensate for the coverage gap.

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+resource (make a user's map public) and the concrete effect: a /map/<handle>/<slug> link viewable by anyone. That is clearly distinct from the inverse sibling unpublish_map, though the description never names that sibling explicitly.

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 purpose implies when to use it (sharing a map publicly), but there is no explicit when-not guidance, no mention of unpublish_map as the reversal, and no prerequisites such as ownership or account requirements.

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

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

Annotations already flag destructive and idempotent, and the description goes well beyond them: a roughly 1 MB payload ceiling, the guarantee that the link and publish state survive, that old content is backed up, and that style is only replaced "if given". These are exactly the consequences an agent needs before triggering a destructive overwrite.

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 dense sentences, front-loaded with the destructive action and the preserved state right after. Every clause carries information, though the list of replaced fields and the preservation note could be ordered slightly more crisply.

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 no-output-schema destructive tool this covers the essentials (scope of destruction, preservation, backup, payload limit). It stops short of stating authorisation requirements and what the call returns, minor gaps given the annotations.

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 50%: the map parameter is documented in the schema, mapId is not. The description adds real value for map (import format reference plus the ~1 MB limit) but says nothing about mapId beyond the notion of an existing map, so it only partly closes the gap.

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 ("Overwrite") plus the resource (an existing map) and enumerates exactly which parts are replaced: layers, markers, name, description, casualty bar, style. "Existing map" implicitly separates it from create_map, though no sibling is named explicitly.

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?

Usage is only implied: the word "existing" and the preserved link/publish state tell an agent this is for an already-created map, but there is no explicit when-to-use vs create_map or get_import_format, and no stated preconditions (e.g. ownership or required permissions).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful behavioral context by stating results are limited to published maps and by describing the return payload (interactive map link, text version, article), which matters because there is no output schema.

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 compact sentences with zero waste: the purpose and search dimensions are front-loaded, followed by the return shape. Nothing is repeated from the schema or annotations.

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 read-only, zero-required-parameter search tool whose schema is fully documented, the description is essentially complete: it covers scope, searchable fields, and return content. Minor gaps (no mention of result ordering or the default limit behavior) are non-critical and partly covered by the schema.

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%, so the baseline is 3. The description adds combinability semantics ('and/or') that the schema does not state, telling the agent the two filters can be used alone or together, which is genuine meaning beyond the field docs.

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 (find) and resource (published animated maps) and scopes it with domain examples plus the two search dimensions (title/description words and year). It does not name a sibling such as list_maps or get_map, so differentiation is implicit rather than explicit.

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?

Usage is implied by 'by words ... and/or a year', making it clear this is the text/year search entry point. There is no statement about when to prefer list_maps, get_map, or get_public_map instead, and no prerequisites or exclusions are given.

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

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

The annotations declare destructiveHint=false, but the description explicitly states that mode replace 'overwrites an existing map's content,' which is a destructive update. The description adds useful details such as the 2-hour validity window, but this direct conflict with the annotation requires flagging.

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 two tightly written sentences with no filler. The core workflow and mode behavior are front-loaded, making it easy for an agent to parse.

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?

It explains the upload opening and the 2-hour validity window, but omits crucial workflow context such as uploading parts with upload_map_part and completing the upload with finish_map_upload. For a start step in a multi-tool chunked upload flow, that leaves the agent to infer the next required calls.

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 both mode and mapId are already documented in the schema. The description reinforces the replace behavior but adds no syntax, constraints, or defaults beyond what the schema provides.

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 uses a specific verb and resource: it opens an upload for map JSON sent in numbered parts. It distinguishes the tool from network-based uploads and explains create versus replace behavior, though it does not name sibling tools such as create_upload_link or replace_map_content explicitly.

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 usage context is implied: use this when sending map JSON in numbered tool-call parts rather than over the network. However, the description gives no explicit when-not guidance and does not name the alternative sibling tools for direct creation, replacement, part upload, or finishing the upload.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context by stating the externally visible effect that the public link stops working. It does not cover error behavior (e.g., what happens if the map is already private) or permission requirements, so a 4 rather than 5.

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?

One tight sentence with the action front-loaded and the consequence in a useful parenthetical. Nothing superfluous.

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 one-parameter mutation tool with annotations covering the safety profile and no output schema, the description covers the what and the effect. It is missing guidance on the required mapId and on error/idempotency cases, leaving a modest gap.

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?

The single parameter mapId has 0% schema description coverage, and the description never mentions it, its format, or how to obtain a valid id. With low coverage the description is expected to compensate, but it adds nothing about the parameter.

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?

Specific verb+resource: 'make one of the user's maps private again', with the concrete outcome 'its public link stops working'. It is clearly the inverse of the sibling publish_map, though it never names that sibling explicitly.

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 word 'again' establishes the precondition that the map is currently public, so the agent knows the context in which to call it. There are no explicit exclusions or named alternative tools, keeping it short of a 5.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds real beyond-schema context: parts are concatenated in order with nothing inserted between them, re-sending a number overwrites that part, and the response includes length and SHA-256. It stops short of describing what happens if a part is skipped or how many parts total are allowed (the 400 max lives only in the schema).

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 tight sentences, each carrying a distinct fact (identity, ordering/replacement behavior, return value) with no repetition of 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 chunked-upload part tool the description covers the essential mechanics: ordering, replacement, and the returned checksum for verification. It would be fully complete if it pointed at the enclosing uploadId source (start_map_upload) and the follow-up finish_map_upload call.

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 67% and the description clarifies 'part' semantics (numbered, ordered, replaceable), which is useful. But uploadId has no schema description and the tool text never says where it comes from, leaving one required parameter unexplained.

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?

Names a specific verb and resource ('Stores one numbered piece of a chunked map upload') and situates it precisely in the chunked-upload workflow, which cleanly separates it from siblings like start_map_upload, finish_map_upload, and replace_map_content.

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 description makes clear this is a per-part operation within a larger upload and that re-sending a part replaces it, which is actionable guidance. It doesn't explicitly say to call start_map_upload first or finish_map_upload after all 400 parts, so the routing is implied rather than spelled out.

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