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

With no annotations, the description carries the full burden and does well: it discloses caching (the 'cached' field), truncation policy (cut at a line boundary with a trailing note, plus a 'truncation' field explaining what was cut and why), and the topic-filter fallback that returns full content plus a note listing available sections. It does not mention network, auth, or rate-limit behavior, which keeps it short of a 5.

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 core purpose is front-loaded in one sentence, followed by scannable indented blocks for identifier forms, args, and returns. Length is justified because the description is the only place the parameters and return contract are documented.

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?

Absent annotations and absent output schema, the description still supplies the full return shape (type, identifier, url, title, content, truncated, tokens, source_tokens, max_tokens, cached), the error shape with a 'suggestion', and the conditional fields. Nothing an agent needs to call or interpret this tool correctly is missing.

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: identifier forms are spelled out with resolution order, topic is explained with its fallback semantics, and max_tokens is given units (1 token ≈ 4 chars) plus the truncation consequence. This is meaning well beyond the bare string/integer 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?

States a specific verb (Fetch), a precisely bounded resource (one Flutter / Dart SDK / pub.dev documentation page) and the output form (clean markdown). The word 'one' plus the three named source families make it distinguishable from the search-oriented siblings without opening any schema.

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 gives real invocation context by enumerating the identifier forms and the exact resolution order used to disambiguate them (pub:, dart:, library-qualified, bare name with index/fallback chain), which is the main usage decision for this tool. It stops short of explicitly routing between itself and overlapping siblings such as pub_package or flutter_search.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it states per-mention failure isolation, that one bad mention never removes or duplicates another entry, the version-resolution policy (exact pins honored, ranges resolve to newest satisfying release, pre-releases excluded, nonexistent versions reported as missing with nearest releases rather than substituted), and truncation behavior when max_tokens is non-positive.

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 response is long but front-loads the purpose, then uses clearly labeled sections (grammar, resolution semantics, args, returns) so nothing is buried. The grammar catalog is verbose yet functional, since each example documents a distinct accepted form; it stops short of padding.

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?

In the absence of an output schema, the description fully specifies the return object shape, the enum-like set of entry types, per-mention result fields, and the error/suggestion structure. An agent has everything needed to call it and interpret the result without additional fields.

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 largely does: text is defined as any text with zero or more mentions, and max_tokens is explained as a rough token budget with a concrete conversion (1 token ≈ 4 chars) and the non-positive-disables-truncation rule, which the schema does not convey.

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 opening sentence gives a specific verb and resource: parse every @flutter_mcp mention in text and resolve each to its docs. It is a distinct batch-resolution operation, but it never explicitly distinguishes itself from siblings like flutter_docs or pub_package; it only notes that identifier forms match flutter_docs, which mildly blurs the boundary rather than sharpening it.

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 implied by the extensive mention-grammar catalog, which suggests the tool is for free text containing @-mentions. However, there is no explicit when-to-use versus flutter_docs/flutter_search/pub_package guidance and no stated exclusions, leaving the agent to infer the routing decision.

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

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.

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

With no annotations, the description carries the full burden and does so well: it discloses the 10s probe timeout, that it never raises (per-check errors only), the degraded-vs-sick distinction for the cache check, the exact overall verdict vocabulary, and the environment variable that disables the politeness layer. These are non-obvious operational traits an agent could not infer from the schema.

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 core purpose is front-loaded in the first sentence, and the remaining paragraphs each cover a distinct concern (degraded cache semantics, probe behaviour, politeness counters). It is prose-heavy and the doubled backticks read awkwardly, but very little of it 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?

There is no output schema and no annotations, so the description must convey the return shape — and it does, describing per-check status, the overall verdict, and the top-level politeness block. Only the usage/alternative question against 'health_check' is left unanswered.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-argument tool is 4. No parameter-level detail is missing.

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 opening line states a specific verb+resource and enumerates what the check inspects (search index state, cache stats, live API probes), which is far more than a tautology. However, it never distinguishes itself from the sibling tool literally named 'health_check', leaving the agent to guess which diagnostic to call.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named even though 'health_check' is a sibling with an overlapping purpose. Usage is only implied by the word 'Health check'; for a diagnostics tool with a near-duplicate sibling, that is a real gap.

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

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 implicitly conveys a safe, idempotent read and discloses the return payload (version), which is useful. It does not state whether auth is required, whether it can fail/timeout, or what 'up' means operationally, but for a trivial probe the disclosure is reasonable.

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 tight sentence with zero waste, front-loading the primary action (check server is up) before the secondary outcome (report version).

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?

With no output schema, the description steps in to say it reports the version, which is the key return detail. For a zero-param probe with no annotations this is nearly complete; a note on failure mode or the distinction from flutter_status would close the remaining gap.

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 tool takes zero parameters (schema coverage 100%), so there is nothing to document and the baseline of 4 applies. The description correctly signals a no-argument call.

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: checks server availability and reports its version. The action is unambiguous. However, it offers no differentiation from the similarly-named sibling flutter_status, which an agent could plausibly confuse with a server health probe.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of when this should be preferred over flutter_status. Usage is only vaguely implied by the verb 'check'.

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

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

With no annotations, the description carries the full burden and does most of it: it discloses the exact return shape, truncation semantics (cut at a line boundary with a trailing note), the error object, nullability of publisher/likes/pub_points, and a cached flag. It stops short of noting rate limits or caching/TTL behavior beyond the flag.

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-loaded one-line purpose followed by tight Args and Returns blocks; the field enumeration of the return object is long but justified by the absence of an output schema. Minor redundancy in re-explaining truncation and token counts, but nothing egregious.

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 3-param tool with no annotations and no output schema, the description covers purpose, every parameter, the full return contract, truncation, and the error case. Nothing an agent needs to invoke or interpret the call correctly appears missing.

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: package_name is called out as exact and case-sensitive with an example, version is optional with a 'latest' default and example, and max_tokens is defined as a rough budget with a 1 token ≈ 4 chars conversion and cut behavior.

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?

Specific verb+resource: 'Fetch pub.dev package metadata plus its README as markdown.' It is clearly distinct from siblings like flutter_docs (documentation), flutter_search (search), and flutter_mentions, so an agent can route to it without ambiguity.

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 implied through the args section (need an exact package name, optional version) rather than stated. There is no explicit 'use this when... / not when...' and no named alternative, though none of the listed siblings competes for package-metadata retrieval.

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