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

With no annotations, the description carries the full behavioral burden and does so well: it discloses case-sensitive prefix matching, restriction to indexed plaintext fields, masking of recipient identifiers, account scoping, and the authentication requirement. This goes well beyond a vague 'search' statement and helps the agent predict behavior.

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 front-loaded: the first sentence states the core behavior, followed by precise matching/scoping constraints and a concise authentication note. Every sentence earns its place; there is no filler or repetition of schema fields.

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?

For a search tool with four parameters, no output schema, and no annotations, the description covers the essential behavioral caveats an agent needs to invoke it correctly: account scoping, match semantics, masking, bucket options, and the fact that start_login is not a prerequisite through this tool. Nothing critical is missing.

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 the baseline is 3, but the description adds meaning beyond the schema by clarifying matching semantics: case-sensitive, prefix-anchored, only over indexed plaintext fields, with masked recipient identifiers. This materially enriches the meaning of the 'q' parameter and the overall search scope, while limit and environment remain adequately documented by 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?

The description opens with a specific verb and resource: 'Prefix-anchored global account search across six resource buckets' and enumerates exactly which buckets. It clearly distinguishes this as an account-wide search tool rather than a single-resource getter or list tool, despite the generic name 'search'.

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 gives clear usage context: it is a global cross-bucket search scoped to the authenticated account, and it provides explicit authentication prerequisites plus a direct exclusion ('start_login does NOT open this tool'). However, it does not explicitly name list_* or get_* siblings as the alternative when a single bucket or specific resource is already known.

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