Search the IaC security corpus

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 discloses the retrieval algorithm (BM25 + dense + RRF), the targeted corpus, and the exact return payload (document title, heading path, URL, verbatim content). While it does not explicitly state side-effect freedom, the language is consistent with a non-mutating search operation.

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 a tight two-sentence structure. The first sentence states the method and corpus; the second defines the return format. Every sentence adds critical information, and the most distinguishing element (retrieval over specific guidance sources) 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?

The description covers the corpus scope, the retrieval method, and the exact contents of the returned chunks, which is sufficient given the simple two-parameter schema and existing output schema. It omits explicit usage guidance and caveats, but these are minor for a straightforward read-only search tool.

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 provides no parameter descriptions, so the tool description must compensate. The phrase 'top-k matching chunks' clarifies the top_k parameter's role, and 'retrieval' implies query is the search text. However, the description does not explain query formulation, permissible input types, or top_k bounds, leaving the agent to infer most semantics.

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 and resource: 'Hybrid (BM25 + dense + RRF) retrieval over CIS AWS Foundations and OWASP CI/CD Top 10 guidance.' This clearly differentiates the tool from siblings like scan_terraform_plan (scanning actions) and list_sources (listing sources), making the tool's purpose unmistakable.

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 implies usage by describing what the tool searches and returns, but it never explicitly states when to use this tool versus the siblings or any exclusions. The purposeful phrasing 'retrieval over CIS AWS Foundations and OWASP CI/CD Top 10 guidance' makes the use case inferable, yet explicit guidance is absent.

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