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

Beyond the annotations, the description discloses the required X-Agent-Key header, confirm:true, and that no webhook or HMAC key is needed. It also explains the event semantics (public incident records first recorded after watch creation, not current reachability) and the deliver_to_inbox side effect including Voidly's read access to those notices.

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 four sentences are front-loaded with purpose, then auth requirements, event semantics, and the inbox side effect. Every sentence adds operational value, and there is no redundant restatement of schema fields.

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 and useful annotations, the description gives enough context about auth, confirmation, event meaning, and inbox side effects to call it correctly. It is slightly incomplete on min_severity behavior and duplicate/re-add semantics, though the schema covers part of the latter.

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 description adds meaningful semantics for confirm and deliver_to_inbox, including the privacy implication that Voidly can read inbox notices, and it names the incident_type values. However, it does not explain min_severity, leaving one schema parameter without additional descriptive coverage.

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 ("Add") and resource ("one pull-feed watch") and explicitly scopes it to a country, domain, or incident type. It also clarifies that this creates a watch for future incident records, separating it from polling or listing siblings.

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 that this is the creation path for a pull-feed watch and mentions required confirmation and auth setup, but it does not explicitly say when to use this versus sibling tools such as watch_list, voidly_watch_poll, or watch_delete. Usage is therefore implied rather than fully guided.

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