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

Annotations already cover safety and idempotency, and the description adds useful behavior beyond them: whole-data-set scope, newest-first ordering, alias compatibility, and the fields included in each entry. This is enough for an agent to understand how the feed behaves without inferring from annotations alone.

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 alias status is front-loaded, followed by a dense but useful sentence covering scope, ordering, purpose, and entry contents. There is no wasted text.

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?

Given rich annotations, full schema coverage, and an output schema, the description supplies everything the agent additionally needs: alias context, global scope, polling suitability, ordering, and event contents.

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 parameter meanings are already documented in the schema. The description reinforces the since-date scope and names the outcome values, but it does not add syntax or filtering semantics beyond what the schema provides, so baseline 3 is appropriate.

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 verb and resource: it returns everything that changed in the whole data set since a date, including verification events and rule changes. It also distinguishes itself from its canonical sibling by explicitly calling itself an alias of dogpolicies_changes_since kept for older clients.

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 gives a clear usage context: an agent can poll cheaply instead of re-reading every record, and older clients can use it as an alias. It does not explicitly say when to prefer dogpolicies_changes_since or dogrulebook_changes_near, but the alias framing provides strong routing guidance.

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