diagnose_flutter_errors

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

No annotations are provided, so the description carries the full burden. It discloses that the tool diagnoses but doesn't disclose how it operates (e.g., whether it returns a fix, whether it requires all parameters, or whether it's a read-only analysis). It also doesn't mention any side effects, limitations, or what the output contains. This is a moderate gap, but the description does name the specific error types, giving some behavioral context.

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 one sentence, concise and front-loaded with the primary action and scope. It uses a colon to list specifics. It's efficient and clear, though it could be even more structured by separating the list into a separate sentence.

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?

Given the tool is a diagnostic service with 4 parameters and no output schema, the description should clarify what kind of output the agent can expect (e.g., explanatory text, suggestions). It also doesn't state whether the tool handles only the listed error types or also others. It's adequate but leaves some key context (return value, scope limitations) unspecified.

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%, so the schema already documents each parameter. The description doesn't add deeper meaning beyond the schema — it doesn't explain how to combine them or which parameter is most essential (errorMessage is required). It just lists the error types, which helps map to inputs but doesn't go beyond 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 states a specific verb ('Diagnoses') and clears resource ('Flutter errors'), and enumerates the categories of errors it handles. However, it doesn't differentiate from the many sibling tools beyond the obvious — there's no explicit statement of what this tool is not, nor does it distinguish from other diagnostic-like tools (e.g., audit_flutter_codebase). It's clear but not distinguished.

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 implies when to use it — when encountering Flutter errors of the listed categories — but there's no explicit guidance on when not to use it or which sibling tools are alternatives. It would benefit from a note like 'For general code audits, use audit_flutter_codebase instead.' Without exclusions, it's merely implied.

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