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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral detail: it returns the framework, asset rows, cells, and prompts, and explains the privacy model ('never requests your program docs... keeps them local'). This gives the agent clear insight into what happens during invocation.

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?

Though moderately long, every sentence serves a purpose: main action, return values, use case, limitation + alternative, privacy note. The description is front-loaded with the purpose, and structure is logical and scannable.

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?

There is no output schema, so the description fully covers return values (framework, asset rows, cells, prompts). It also explains which inputs are supported, when to use an alternative, and the privacy behavior, making it complete for this simple 1-parameter lookup 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?

Schema description coverage is 100%, with the concept parameter already documented with patterns and length constraints. The description adds examples and case-insensitivity, but these largely mirror the schema. Baseline of 3 is appropriate because schema does the heavy lifting.

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: 'Reverse-lookup a single concept ID... across the AI Defense Matrix.' It clearly lists example IDs and return elements, and explicitly distinguishes itself from the sibling tool aidefense_get_framework_alignment for prose-only frameworks. This provides a fully clear and unique purpose.

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 gives explicit use case ('Useful when a vendor's product is defined by a specific technique...') and states a direct alternative: 'for prose-only frameworks... use aidefense_get_framework_alignment instead.' It also sets a boundary on what inputs it accepts, preventing misuse with unsupported framework IDs.

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