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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the search is hybrid BM25 + vector, returns only excerpts with deep links, and never full pages. These are meaningful behavioral traits beyond the schema. It does not mention rate limits or auth, but for a read-only search tool the key return behavior is well covered.

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 sentences with no filler. The first sentence states the action and method; the second explains return behavior and the follow-up tool. Every clause earns its place, and the most important information is front-loaded.

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 simple two-parameter search tool with no output schema, the description covers the essential context: what it searches, how it searches, what it returns, and what to do next. It could mention result ordering or pagination, but the direct pointer to get_doc makes the workflow complete enough for an agent to use it correctly.

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 already describes both parameters with 100% coverage (query as natural-language search query, limit with default and bounds). The description adds the semantic search context, which indirectly clarifies that the query should be phrased naturally, but it does not provide additional parameter-specific semantics. Baseline 3 is appropriate.

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 states a specific action ('Search the StitchAPI documentation') with a clear method ('semantically (hybrid BM25 + vector)') and resource. It also explicitly distinguishes itself from get_doc by noting it returns excerpts and never full pages, so an agent can tell them apart without inspecting the sibling.

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 concrete guidance on when to use this tool versus the alternative: use search_docs for relevant sections/excerpts, then 'Follow up with get_doc to read a full page.' This clearly frames the search-then-read workflow and implicitly states when not to use it (when full pages are needed).

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