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

Annotations already mark this as read-only, idempotent, and non-destructive (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description goes beyond these by disclosing the default parameter behavior ('include_body' defaults to false), the branching logic for empty results, and the result grouping/pagination behavior — all genuinely useful for an agent deciding whether search will satisfy the task without side effects. The inclusion of the 'include_instructions' default tied to include_body and the empty-result onboarding guidance is unusually transparent. No contradiction with 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?

Front-loaded with the core purpose, then the key differentiator, then behavioral specifics, then parameters. It's long, but nearly every sentence adds operational value, and the alternatives/division between behavior and empty-state guidance is coherent. The parameter enumeration is dense but earned given the 16 parameters.

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?

Covers the core use case, return grouping/pagination, result structure (include_body vs include_instructions), edge case behavior (empty results → call `me`), and parameter semantics like container_id being ignored when search_scope is team-wide. Combined with a rich schema and clear annotations, this is a complete operational picture.

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 input schema covers all 16 parameters with descriptions, so baseline is 3. The description adds genuine value by clarifying the default behaviors (types default to all three, include_body default false, include_instructions defaults to include_body), the AND logic for tags, the ignored condition for container_id, and the semantics of inherited instructions. It doesn't fully explain every parameter, so not a 5, but it materially enriches the schema.

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+resource ('Search across notes, containers, and tags') and immediately differentiates itself as the go-to tool for retrieving anything the user has previously saved, contrasting with sibling tools that manage those entities (e.g., containers-create, containers-update). The exhaustive list of content types makes the scope unmistakable, and the phrasing 'Returns results grouped by type' adds concrete output behavior an agent can rely on.

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?

Clearly establishes when to use the tool ('When a task needs something the user previously stored') and describes the fallback action when results are empty ('call `me` and follow onboarding.next_action'), which is a genuinely useful decision rule. However, it doesn't explicitly state when not to use it in favor of a specific sibling tool, so a 5 isn't earned, but the context provided is strong.

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