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

Annotations already signal a non-read-only, non-destructive write, and the description adds meaningful behavior beyond that: cross-agent dedup, the nightly sweep over active rows, and active/removed semantics via the stage field. It also discloses the return shape with created/updated/skipped counts. This is a useful, non-contradictory behavioral context.

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 compact and well-structured: a summary sentence followed by a returns note. It front-loads the action, includes the meaningful dedup and nightly-sweep context, and does not repeat schema details or add fluff.

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 tool has only two required parameters, both fully described in the schema, and the description covers the activation behavior and returns summary despite no output schema. Minor omissions like expected permissions or edge cases around duplicate items are not critical, so the definition is nearly complete for correct selection and invocation.

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 items parameter is already well-documented with identifier, display_name, stage, and data. The description does not add new parameter-level meaning; it only restates the bulk-add purpose and return counts. Baseline 3 applies because the schema carries the parameter burden fully.

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 a specific action and resource: 'Bulk-add companies to an agent's monitoring list.' It also clarifies scope with 'cross-agent dedup' and the activation effect on the nightly sweep. This clearly differentiates it from update/edit/sibling tools by emphasizing bulk-adding rather than modifying or querying.

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 conveys when it applies by saying adding companies here turns monitoring on, which implies the use case. However, it never mentions alternatives such as edit_monitor_members, update_monitored_company, or query_monitored_companies, and gives no 'when not to use' guidance. The usage context is clear but not explicitly routed against siblings.

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