encoding_decoding_punycode

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds 'Pure in-process compute, no DNS or network lookup' and rate limits (60/120 per min), providing context beyond annotations.

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?

Description is concise yet comprehensive, no redundant sentences. Purpose stated first, then usage guidance, then behavioral traits, then return format. 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?

Despite having an output schema, description mentions 'Returns the converted string plus a per-label breakdown and a non-ASCII character listing,' ensuring full understanding. No gaps.

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%, baseline 3. Description clarifies behavior for encode vs decode with examples and domain detection logic (dots vs single label), adding significant meaning 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 explicitly states the tool encodes internationalized domain names to ASCII xn-- form and decodes back, with specific reference to RFC 3492/IDNA. It also names sibling tools for URL encoding and Unicode escapes, distinguishing it clearly.

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?

Provides explicit guidance: use for domain-name encoding where each label is converted independently; directs to encoding_decoding_url for URL paths and encoding_decoding_unicode for arbitrary text escapes. This covers when to use and when not.

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