List Security Guidance

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

Annotations already declare readOnlyHint=true, so the description doesn't need to cover safety. It adds useful behavioral context: the library is global, entries are per OWASP issue, and passing guidanceId returns a single entry with code examples. This goes beyond the annotation to explain return scope and filtering 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?

Three compact sentences with no filler. The verb and resource are front-loaded, the optional-parameter behavior is stated clearly, and the global scope qualifier earns its place by preventing misuse. The parenthetical '(the guidanceId of a finding)' is slightly repetitive but adds clarifying value.

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 simple read-only list tool with one optional parameter and no output schema, the description is complete. It explains what is returned (entries with remediation, code examples, references), the optional single-entry behavior, and the global scope. No critical calling information is missing.

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 documents guidanceId with an example and behavior, so the baseline is 3. The description adds meaning by explaining that guidanceId is 'the guidanceId of a finding', connecting the parameter to findings and helping the agent know where the ID comes from. This is a meaningful addition over the schema's description.

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 states a specific verb ('List') and a specific resource ('static security guidance library'), and clarifies the content ('one entry per OWASP API-security issue with its remediation text, code examples and references'). It distinguishes itself from siblings by emphasizing 'static' and 'global, not project-specific', which separates it from dynamic security findings or project-scoped guidance tools.

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 clear context for when to use the tool: it is a global, static guidance library, and optionally accepts guidanceId for a single entry. It does not explicitly name alternatives or exclusions, but the 'static' and 'global' framing implies when this tool is appropriate versus project-specific or dynamic security tools.

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