Consultar hallazgos

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

The readOnlyHint=true annotation already establishes the safety profile, so the description only needs to add context. It does disclose the default run selection ('por defecto la última'), which is real behavioral information, but says nothing about result ordering, pagination behavior, or whether the default status filter is applied — a notable omission for a query tool with a documented default of hiding discarded findings.

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?

A single dense sentence with zero filler, and the core action plus resource is front-loaded before the filter list. The mid-sentence parenthetical about the default run is slightly disruptive but carries real information, so almost nothing is wasted.

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 nine-parameter, zero-required query tool with no output schema and only a readOnlyHint annotation, the description is adequate but thin. It never states what a result looks like or how pagination/limit interact with the total result set, which is the main gap an agent would hit when actually calling it.

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 44%, so the description must compensate for the undocumented parameters. It partially does: the listed filter dimensions map onto min_severity, category, tool, status, file, and search, giving the agent a coherent model of the filtering surface. However, it adds no syntax or format detail, and limit/offset (including the 500 maximum and paging semantics) are covered by neither the description nor the schema.

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 gives a specific verb ('Filtra') and resource ('los hallazgos de una corrida') and enumerates the filter axes (severity, category, tool, triage status, file, text), so the agent knows exactly what it returns. It does not name the sibling that handles the adjacent single-record case (finding_get) or triage mutation (finding_triage), so differentiation from siblings is left implicit.

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?

Usage is only implied by the verb: filter findings of a run. The one useful routing cue is the default to the latest run, but there is no explicit when-to-use vs. when-not, and no pointer to finding_get for a single finding or finding_triage for changing status, which are the obvious alternatives in this toolset.

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