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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context by noting that exact tokens work best and that plain questions work too, which helps the agent set expectations about search quality. It also discloses that the tool returns ids (not full content), which is a key behavioral trait beyond what annotations provide. The description does not contradict 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?

The description is compact and front-loaded: it states the tool's purpose in the first sentence, then provides search tips and the return contract. Every sentence earns its place, and there is no redundant repetition of schema details. The structure is easy to scan and understand.

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 the tool's simplicity (3 params, 1 required, output schema present), the description is complete. It covers what the tool searches, how to search effectively, and what the return value is. The output schema exists, so the description doesn't need to explain return values in detail. The sibling context (fetch, get_endpoint, list_endpoints) is handled by the explicit mention of returning ids to pass to `fetch`.

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 67% (query and scope have descriptions, limit does not). The description adds value by explaining that exact tokens like field names, status codes, and paths work best, and that the result is ids to pass to `fetch`. This goes beyond the schema's parameter descriptions. The limit parameter lacks a description in the schema, but its name and default are self-explanatory, and the description doesn't need to elaborate.

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 clearly states the tool performs full-text search over Wikimedia Enterprise API documentation, enumerating the content types covered (guide sections, changelog, pricing, endpoints, response models). It distinguishes itself from siblings by explicitly mentioning that it returns ids to pass to `fetch`, which is a sibling tool. The verb 'search' plus the resource scope makes the purpose unambiguous.

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 provides explicit guidance on when to use this tool: it is for searching documentation, and it tells the agent that exact tokens work best (field names, status codes, paths) while plain questions also work. It also explains the return value is ids to pass to `fetch`, which implicitly routes the agent to the correct next step. The scope parameter is described in the schema, and the description reinforces the distinction between docs and reference content.

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