search_docs

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

With no annotations, the description carries the full burden. It adds meaningful behavioral context: results carry source/index stamps, the backend is a local index over live-fetched docs, and the Ask AI knowledge graph will replace it. It does not explicitly state read-only behavior or auth requirements, but for a search tool the absence of side effects is implied.

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 reasonably concise, with a clear first sentence and two short paragraphs. However, the second sentence is dense, bundling three distinct ideas (orchestration restriction, result stamps, backend details) which could be separated for clarity. Still, every sentence earns its place.

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 moderate complexity and the presence of an output schema, the description covers the scope, the grounding-only usage, result characteristics, and backend implementation. It does not explicitly describe the output structure, but the mention of 'source and index stamp' and the existing output schema mitigate that. Overall, it provides enough context for an agent to use the tool 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 has 0% description coverage, and the tool description does not describe the 'query' or 'limit' parameters beyond their names and defaults. It does not explain query syntax, what the limit controls, or how results are ordered. The description adds no parameter-level meaning.

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 'Search the documentation corpus' and enumerates the specific sources (dapi user guide, ds-workflows book, SimCenter quoFEM docs, reference manuals). It explicitly distinguishes itself from search_snippets by clarifying that this tool is for grounding, not for composing runs.

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?

It gives explicit guidance: 'Grounding only, never the source of orchestration code' and points to snippets as the only source for composing runs. This clearly delineates when to use this tool versus the sibling search_snippets.

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