flutter_search

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

With no annotations, the description carries the burden and does well: it discloses the ranking algorithm (exact > prefix > substring > fuzzy), the 'index_stale' flag, and the alternate error/suggestion return shape. It doesn't state read-only safety explicitly or mention rate limits, but search semantics make the safety profile unambiguous.

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?

Front-loads purpose and ranking, then organizes Args and Returns into clearly labeled blocks with no filler. The multi-line Returns blob is slightly dense but every sentence earns its place.

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?

There is no output schema, but the description compensates by enumerating the return fields (name, library, kind, url, score) and the failure shape. Combined with parameter docs, an agent has enough to invoke and interpret results correctly; only error-handling guidance is thin.

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, and it does: it defines query as text matched against class names with concrete examples ('text field', 'ListView') and limit as the maximum result count with its default. This is meaningful added value beyond the bare schema, though it is terse.

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?

States a specific verb and resource ('Search Flutter and Dart SDK class names') and clarifies scope with 'plus enums/mixins/typedefs'. It also names the sibling relation to flutter_docs, letting an agent distinguish it from the other lookup tools without opening schemas.

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?

Explicitly instructs the agent to 'find the right identifier before calling flutter_docs', which is clear routing context. It stops short of stating when NOT to use it or naming non-flutter_docs alternatives, so it does not reach a 5.

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