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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral detail beyond that: the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, the 200K char cap with truncation flagging, and the output structure (character offsets, similarity scores). It also notes 'every passage carries an offset so the agent can verify a verbatim quote,' which is extra transparency about output verifiability. No contradictions.

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 five sentences, each earning its place: the core action, the input/output contract, the primary use case, the sibling pairing, and the technical embedding/limit details. It is front-loaded with the most important information and avoids redundancy with the schema. No wasted words.

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 no output schema, the description appropriately explains the return values (top-N passages with character offsets and similarity scores). It covers the complete workflow, including the input source, the query, the limit default (mentioned in schema), the max text size, truncation behavior, and the companion tool. For a search tool with three simple parameters, this description is fully sufficient to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description adds contextual meaning beyond the schema: it clarifies that 'text' is the previously fetched record (e.g., SEC 10-K body), that 'query' is a natural-language request with examples, and it reinforces the limit's purpose with 'top-N passages.' The description also mentions the 'truncated and flagged' behavior tied to the text cap, which enriches the parameter semantics beyond raw schema constraints.

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+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes itself from siblings by emphasizing that it operates on already-fetched text, and it explicitly differentiates from ask_pipeworx_grounded by framing this as the passage-level search companion. The purpose is unambiguous and not tautological.

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 states exactly when to use this tool: 'Use when the record is too big to cram into the prompt.' It explicitly names the alternative workflow with ask_pipeworx_grounded, explaining how to fetch with the gateway and then ground over relevant passages. This is clear, actionable guidance and gives an exclusion (when you don't need full-text grounding).

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