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

Annotations already cover readOnly/idempotent/destructive/openWorld, so the description need only add context. It usefully discloses the scope restriction (only pages shared with Wavelength) and the unconnected-app failure behavior, both of which go beyond the annotations.

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 short sentences, front-loaded with the core purpose and free of filler. The error-handling sentence is arguably peripheral but still actionable, so it earns its place.

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?

No output schema exists, so the description should ideally describe the return shape; it only hints at it via 'use a page_id,' which lets an agent infer page_ids are returned. Combined with the scope and error context, it is nearly complete for a one-param read tool.

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 single 'query' parameter is 100% described in the schema ('Words in the page title. Leave empty for recent pages.'), so the description adds nothing beyond it. Baseline 3 applies when schema coverage is high and the description does not enrich parameter meaning.

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 (search) and resource (Notion pages) with a scoping qualifier ('that the user shared with Wavelength'). An agent can tell it apart from find_confluence_targets/find_jira_targets by the resource, though the description does not explicitly contrast those 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?

'Use a page_id as the parent for send_flow_to_notion' names the downstream tool and the condition tying this search to it, which is clear context. It does not state when NOT to use it or name the competing find_*_targets siblings, so it stops short of explicit alternatives.

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