flutter_knowledge

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

With no annotations provided, the description carries the full disclosure burden. It calls itself 'opinionated' (a helpful trait disclosure) and implies a read/knowledge-retrieval operation, but it doesn't state return format, scope limits, or whether answers reflect a specific framework version/state. The 'current best-practice' phrasing signals temporal relevance but the mechanism (how current, how opinionated) is undisclosed.

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?

Two sentences, front-loaded with the core purpose ('Opinionated, current best-practice guidance for Flutter projects'), then a topic list, then usage directive. Every sentence earns its place; the topic enumeration is not wasteful because it doubles as query guidance for the agent. Zero filler.

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 single-parameter knowledge-lookup tool with no output schema, the description covers topic scope, query format, and usage mode (topic or entry id). It doesn't explain what the response looks like (single answer, excerpts, links), but for a lightweight retrieval tool among many siblings, this is nearly complete. Minor gap: no note about response structure or whether multiple topics can be combined in one query.

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 coverage is 100% and the query parameter is well-documented ('Topic, question, or entry id') with concrete examples. The description complements this by listing valid topic areas and clarifying that the query can be either a topic or an entry id, adding meaning beyond the bare schema without redundancy.

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 purpose: providing opinionated, current best-practice guidance for Flutter projects, enumerating concrete topics (architecture, state management, theming, error handling, flavors/CI, package picks). It clearly distinguishes itself from sibling tools like flutter_docs (reference docs) and flutter_source_search (source code lookup) by being opinionated guidance rather than raw reference material.

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 gives clear guidance on how to query ('by topic or entry id') and enumates example queries. While it doesn't explicitly state when not to use versus alternatives, its positioning as opinionated best-practice guidance implicitly differentiates it from pure reference tools like dart_language_ref and flutter_docs. A brief note on when to prefer it over siblings would push to 5.

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