search_suggest

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: pages are included by default, users/groups are off by default, and include_pages=false is the way to skip pages. This explains real default filtering behavior that the schema does not fully convey.

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 two short sentences with no filler. The core purpose is front-loaded, and the second sentence efficiently conveys the most important default-toggle behavior. Every word contributes to usable guidance.

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 read-only suggestion tool with six mostly self-explanatory parameters, annotations covering safety, and no output schema, the description is nearly complete. It explains the key defaults but does not describe the return value structure or explicitly mention space scoping, which would make it fully self-sufficient.

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 50%, and the description partially compensates by explaining the default states of include_pages, include_users, and include_groups. However, it does not clarify how space_id scopes suggestions, what the limit controls beyond 'page size,' or the matching semantics of query, so the agent still has to infer some parameter behavior.

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 begins with 'Typeahead suggestions,' which clearly identifies the tool as returning lightweight suggestion results for autocomplete-style queries. It distinguishes from sibling search tools like search_pages and search_attachments by implying real-time, partial-match suggestions, though it does not use an explicit verb like 'returns' or 'lists.'

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 'Typeahead suggestions' establishes the tool's intended context: use it when you need progressive suggestions as the user types. It does not explicitly name alternatives such as search_pages for full result searches, so it stops short of full when-not guidance, but the typeahead framing is clear enough for selecting this tool over broad search siblings.

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