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

Despite annotations already indicating read-only, open-world, and idempotent behavior, the description adds substantial non-redundant detail: the exact embedding model (BGE-base-en), chunking method (500-char overlapping windows), scoring mechanism (cosine), output structure (character offsets and similarity scores), and the 200K character cap with truncation flagging. This goes well beyond the annotation hints and sets clear expectations for edge cases.

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 well-structured with a front-loaded main purpose, followed by usage guidance and technical specifics. While it is slightly verbose in repeating the context-saving benefit, every sentence carries functional weight. It remains compact relative to the amount of behavioral detail conveyed.

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?

No output schema is provided, so the description takes on full responsibility for explaining return values. It clearly states the output includes top-N passages with character offsets and similarity scores, and mentions the truncation flag for oversized inputs. This provides an agent with all necessary information to invoke the tool and interpret results confidently.

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 schema already provides 100% parameter coverage with clear descriptions for text, query, and limit. The description reiterates the text source and query purpose, and notes 'top-N passages' which maps to limit, but adds limited new semantics beyond what the schema already provides. 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 clearly states the tool's function: 'Semantic search INSIDE a fetched record.' It provides concrete examples ('SEC 10-K body, an article, a long tool result') and explicitly differentiates from siblings by pairing it with ask_pipeworx_grounded. The verb 'search' and resource 'a fetched record' are specific and 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?

Guidance is explicit: 'Use when the record is too big to cram into the prompt — search_within saves context, returns only the passages that matter.' It also names the complementary tool ask_pipeworx_grounded and explains how to combine them ('fetch with the gateway, ground over the relevant passages'), giving clear when-to-use and when-to-pair context.

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