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

Annotations already indicate readOnlyHint=true and idempotentHint=true, covering safety. The description adds valuable context by disclosing the return format (matching templates with title, framework, slug, source_refs, and excerpt) and the full-text scope. This goes beyond the annotations and schema, providing a clear picture of the tool's behavior.

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, front-loaded with the main purpose, and includes no filler. It effectively balances brevity with necessary detail about filtering and return fields.

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 read-only search tool, the description is complete. It states what is searched, the filtering options, and the exact fields returned. Since there is no output schema, listing the return fields is especially valuable. The annotations cover safety, and the schema covers parameters adequately.

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 describes keyword and framework, with descriptions for both. The description adds the list of allowed framework values and confirms keyword matches title+body. However, the 'limit' parameter has no description in either the schema or the description, though its constraints (default 10, max 50) are present in the schema. Overall, the description partially supplements the schema but doesn't fully compensate for the missing 'limit' 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 uses a specific verb ('Full-text search') with a clear resource ('the curated NORMA control corpus'), and explicitly mentions filtering by framework and the return fields. This clearly distinguishes it from sibling tools like assess_gap, generate_policy, and map_controls, which serve different purposes.

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 clearly states what the tool does and mentions the framework filter as a usage option. However, it does not explicitly compare with sibling tools or state when not to use this tool, so it falls short of a 5. The purpose is clear enough that an agent would know to use it for full-text search of controls.

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