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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, yet the description adds real context: it reads stored evidence without contacting a provider, notes can be held, and held notes report enumerated reasons with a writer-facing deliveryNote. This meaningfully exceeds the annotation surface, though much of it drifts toward return-value territory the output schema already covers.

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?

Front-loaded with the core verb+resource, then layers scope and state semantics in a few dense sentences. It is jargon-heavy but every sentence carries information; nothing reads as filler beyond the parenthetical reason list.

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?

Because an output schema exists, return values need not be documented, yet the description still spends most of its length on them while leaving the input filters under-specified. For a 7-parameter, 0-required list tool it covers scope adequately but is incomplete on filtering behavior.

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 only 29% (writer and workspace are documented; to, from, kind, limit, and status are not). The description compensates only for the writer/workspace authorization semantics and describes accountId/accountCanChange, which are output fields, not the undocumented input filters, leaving the date-range, kind, status and limit parameters unexplained.

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?

States a specific verb (List) and resource scope (Notes and Articles in a bounded schedule view) and enumerates what the view carries. An agent can grasp what comes back, though it never names the nearest sibling (list_scheduled_posts) to disambiguate 'items' from 'posts'.

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 phrase 'one bounded schedule view' implies when this list is appropriate, and the scope rules (workspace/writer team Notes vs private team Articles) hint at authorization context. However, there is no explicit when-to-use/when-not, and no routing to alternatives such as list_scheduled_posts or get_scheduled_item_readiness.

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