list_smell_findings

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It only mentions filtering criteria but doesn't explain pagination (limit/offset), ordering, empty results, or error behavior. The dashboard note is usage context, not actual tool 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 short sentences with the core purpose front-loaded and no redundant text. It is appropriately concise and well-structured.

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 7-parameter tool with no annotations and no output schema, the description is too sparse. It doesn't describe the return value structure, pagination behavior, or constraints on jobId. The dashboard context doesn't satisfy the need for more complete tool documentation.

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 description names severity, name, and filePath as filter dimensions, which adds meaning to those schema parameters. However, it doesn't mention the required jobId explicitly or address pagination parameters (limit, offset), and schema coverage is only 57%, so it only partially compensates for the gaps.

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 clearly states it retrieves a finding list for a specific job with filtering by severity, name, filePath, etc., and mentions the dashboard detail table use case. This distinguishes it from sibling tools like list_smell_analyses (which lists analyses) and get_smells_by_file (which is file-specific).

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 provides clear usage context by explicitly stating it's used for displaying a dashboard detail table. However, it doesn't mention when not to use it or name alternative tools like get_high_severity_smells or get_smells_by_file, so it stops short of explicit exclusion guidance.

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