omni_map_changelog

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

With no annotations, the description carries full disclosure and does it well: append-only, 'existing history is never rewritten,' and the correct-by-appending workflow. This makes the non-obvious side effects visible without needing initialization or auth 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?

Three sentences, each adding a distinct fact: core action, mandatory usage, and correction/read modes. No repetition, no filler, and the main verb appears first.

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?

The core behavior, required usage context, and mode switching are all covered, and the schema documents the remaining parameters. It does not state return values or failure behavior, but with no output schema and 93% parameter coverage this is a minor 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?

Schema coverage is 93%, so the baseline is 3. The description goes beyond the schema by explaining how corrects and read alter the behavior, which is parameter-level semantic guidance the schema does not provide.

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 opens with a specific verb and resource: 'Append an entry to a map's CHANGE_LOG.md.' It distinguishes the write mode from read mode and from correction-by-append, making the tool's purpose unambiguous.

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?

It states 'Required at the end of every task,' giving an explicit trigger. It also explains when to use read:true and how to handle corrections via corrects rather than editing, so an agent knows the three invocation variants.

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