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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description reveals important behavior: the badge shows coarse time rather than a live clock, the reason is server-side caching, the returned value is both a Markdown and HTML snippet, and the image is always wrapped in a link. This transparently sets expectations and prevents misuse. There is no contradiction with the annotations: returning generated snippets is consistent with a read-only hint.

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 longer than average, but it is dense and every sentence earns its place: it explains the core distinction from an iframe, the coarse-time behavior, the caching rationale, the return format, and the mandatory link. It could be trimmed slightly, but the extra length is justified by the behavioral nuance and the prevention of incorrect use.

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 there is no output schema, the description does a good job of explaining what the agent will get (Markdown and HTML snippets), how to choose between them, what the badge will and will not do (coarse, not ticking), and the non-negotiable link wrapping. The only minor gap is not explaining whether the countdown starts at call time, but the schema's duration semantics make that reasonably inferrable. The description is complete enough for correct selection and invocation.

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?

Input schema coverage is 100%, and each parameter already has a clear description. The tool description does not add any new per-parameter syntax or constraints, so the baseline of 3 is appropriate. It does reinforce the output semantics ('coarse time remaining') but not anything about the duration format, label, or badge_style beyond the 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 uses a specific verb-object pair ('create a countdown badge') and immediately clarifies what it is not ('a small image, not an <iframe>'). It names the resource, the output form (Markdown/HTML snippets), and the intended use context (GitHub README, forum signature, Notion page), making it easy to distinguish from sibling and neighboring tools.

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 explicitly says when to use this tool ('for places embed_on_website's iframe cannot go') and even names that alternative. It also gives firm behavioral instructions: 'Always returns the image wrapped in a link to the live countdown — never ask for or produce just the bare image.' It warns against a false expectation (live ticking) and tells the agent to choose whichever snippet the destination accepts. This is strong routing guidance.

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