inspect_finding_or_evidence

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

With no annotations, the description carries the full burden. It usefully discloses that it retrieves 100% original data, raw stdout/stderr, and SHA-256 integrity hashes, but it does not explicitly state read-only behavior, permissions/auth needs, side effects, or error 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 front-loaded and structured with sections, but it is verbose for only two parameters. The guidance and example sections repeat the same finding_id/evidence_id information already stated above, so some sentences do not add new 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?

An output schema exists, so return-value details need not be fully duplicated. The description covers both invocation modes and gives examples, making the tool callable, but it leaves gaps around parameter mutual exclusivity and behavior when no ID is supplied.

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 0%, so the description must compensate. It defines both finding_id and evidence_id with concrete meanings and examples. It still omits optionality, integer format, mutual exclusivity, and behavior when both or neither are provided.

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 investigative/retrieval purpose and clearly separates two modes: retrieving finding details (16 OWASP indicators, remediation) versus evidence details (CLI command, raw stdout/stderr, SHA-256 hash). An agent can understand exactly what resource is being inspected without opening the schema.

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?

It gives explicit usage conditions for each parameter: pass finding_id to see OWASP risk rating details, or evidence_id to extract raw command output and hash, with concrete examples. It does not address alternatives, mutual exclusivity, or what happens if both/neither are supplied, so it stops short of full when/when-not guidance.

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