Update User Map

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds a genuine extra trait not present in the annotations: that the call flushes the MCP cache, which is meaningful side-effect information for a mutation. It stops short of describing permissions, what happens to unmentioned fields, or partial-update semantics.

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 labeled fragments, no filler, purpose front-loaded ahead of side effects. It is efficient, though so terse that it barely qualifies as a description rather than a metadata stub.

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 mutation with a nested freeform object and no output schema, annotations cover the safety profile and the description adds the cache-flush side effect. Still missing is any sense of what fields `settings` accepts or how this differs from create/delete, which leaves meaningful ambiguity for the caller.

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 baseline is 3; `key` (mkey) and `settings` are both documented in the schema. The description adds nothing about the freeform `settings` object, whose updatable fields are opaque (`additionalProperties: {}`), but that gap is not something the description was expected to close here.

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 states the verb and resource only indirectly through the raw REST mapping (`PUT /v1/user-maps/{key}`), without ever saying what updating a user map actually does or what a user map is. The name and title already convey 'Update User Map', so the description adds endpoint identity rather than functional meaning. It does not distinguish this from siblings like users.maps.create or users.maps.get beyond the verb embedded in the path.

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 guidance on when to call this versus users.maps.create, users.maps.delete, or fortimail.cache.flush. No prerequisites, ordering, or conditions are given. The agent must infer entirely from the tool name.

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