Agent Bits

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

With no annotations provided, the description carries the full burden. It discloses that invalid payloads are reported as errors and clarifies that Base64 decoding is not decryption, which prevents misuse. However, it doesn't mention handling of whitespace, padding, or URL-safe variants, which would add more context.

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 structured with a clear opening sentence and succinct bullet points for use and non-use cases. Every sentence adds value, with no redundant 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 one-parameter decode tool with no output schema, the description is complete: it covers purpose, when to use, behavioral details, and parameter meaning via schema. The lack of an output schema is mitigated by the clear statement that it decodes to UTF-8 text.

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 schema already describes the single parameter as 'Base64 text to decode' with 100% coverage, so the baseline is 3. The description's first sentence reiterates 'Base64 string' but doesn't add new semantic details 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 clearly states the function: 'Decode a Base64 string into UTF-8 text and report invalid payloads as errors.' It identifies the resource and action, and distinguishes from siblings by explicitly naming base64_encode, url_decode, and decryption.

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 explicitly provides 'Use when' and 'Do not use when' sections, listing concrete use cases and alternatives. For example, it advises using base64_encode for encoding and url_decode for percent-encoded components.

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 provided, the description carries the full burden. It discloses that Base64 is encoding-only (not encryption/hashing), specifies UTF-8 input and standard Base64 output, and clarifies what it does not do. This adds meaningful behavioral context beyond 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 description is well-structured with a clear first sentence and bullet lists for usage. The 'Use when' bullets are somewhat redundant with the opening line, but the 'Do not use when' section earns its place by providing necessary exclusions. It is not overly long for the value it delivers.

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 the tool's simplicity (one parameter, no output schema, no annotations), the description covers the essential aspects: purpose, use cases, exclusions, and a security caveat. It is sufficiently complete for an agent to select and invoke the tool correctly, though it could state the return format explicitly.

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 input schema already covers the sole parameter with 100% description coverage ('value' described as 'Text to encode'). The description reinforces the UTF-8 string aspect but does not add syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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 opens with 'Convert a UTF-8 string into standard Base64,' using a specific verb+resource that clearly identifies the function. It also explicitly distinguishes from sibling tools like base64_decode and url_encode in the 'Do not use when' section.

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?

Dedicated 'Use when' and 'Do not use when' sections provide clear context for when to apply the tool, and name base64_decode and url_encode as explicit alternatives. This leaves no ambiguity about selecting the right tool.

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 provided, the description carries the full burden. It discloses the payment requirement (0.001 USDC via x402), versioning, and the JSON output format. However, it does not mention potential large response size or latency implications, which are minor gaps for a bulk download tool.

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 well-structured with a clear opening sentence, bullet-point lists for use/do-not-use, and payment info. It is slightly redundant—the opening sentence already mentions caching and multi-country analysis, which the 'Use when' list repeats—but overall it is concise and scannable.

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 the tool's simplicity (1 optional param, no output schema), the description covers the essential context: what it does, when to use it, when not, and the payment model. It could mention error handling or expected response size, but for a bulk download tool, it is largely complete.

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 input schema already documents the only parameter 'version' with a clear description and default value, giving 100% schema coverage. The tool description adds no additional parameter semantics beyond this, so it meets the baseline but does not enhance understanding.

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 clearly states 'Download the complete versioned countries dataset as JSON', using a specific verb, resource, and format. It also distinguishes from siblings by explicitly comparing to 'country_lookup' and mentioning multi-country analysis, making the tool's unique purpose clear.

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 includes explicit 'Use when' and 'Do not use when' sections, listing precise scenarios and naming alternative tools like country_lookup, currency_lookup, and language_lookup. This provides clear, actionable guidance for when to choose this tool over alternatives.

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 takes on the full burden of explaining behavior. It details the output (official name, region, currency, calling code, languages, related metadata) and the input prerequisite (having the two-letter code). It does not explicitly cover edge cases like invalid or unrecognized codes, but the schema pattern addresses format validation, making this a minor gap. The description adds valuable behavioral context beyond the raw tool name.

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 well-organized with a clear purpose statement followed by bullet-point use cases and exclusions. It is front-loaded and every section earns its place, providing usage examples and alternatives without unnecessary fluff. The structure aids quick parsing by an AI agent.

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?

The tool is a simple one-parameter lookup, and the description is complete in scope: it lists the returned metadata categories, specifies the input format, and provides usage boundaries. While there is no output schema, the description compensates by enumerating the output fields. It omits details about error handling for nonexistent codes, but overall it is sufficient for an agent to decide when and how to invoke it.

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 schema already covers 100% of the parameter description, including the pattern and examples ('ISO 3166-1 alpha-2 country code, for example CA or JP'). The tool description reinforces this with examples and the context of 'when you already have the two-letter code,' but does not add substantial new semantics beyond the schema, so baseline 3 is appropriate.

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 clearly states the tool's function: 'Resolve an ISO 3166-1 alpha-2 country code... to official name, region, currency, calling code, languages, and related country metadata.' It uses a specific verb (resolve) and resource (ISO code → metadata), and distinguishes it from siblings by noting it applies 'when you already have the two-letter code.'

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 provides explicit 'Use when' and 'Do not use when' sections with concrete example queries. It names alternatives: countries_bulk for bulk/dataset needs and currency_lookup for ISO 4217 code lookups, offering clear guidance on when to choose this tool over siblings.

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 exist, so the description carries the full burden. It clearly states this is a metadata lookup rather than exchange rate conversion, and outlines the scope including which countries use the code. It doesn't explicitly address read-only nature or error behavior, which is a minor gap for a lookup tool.

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 compact: one sentence for purpose, followed by bullet lists for usage and non-usage. Every sentence earns its place, and there is no redundant or extraneous information.

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 one-parameter lookup tool, the description covers purpose, usage guidelines, exclusions, and return fields (name, symbol, decimal places, countries). It is fully self-contained and clear, even without an output schema.

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 0%, but the description explains the parameter means an ISO 4217 currency code and gives examples (USD, EUR, JPY). This fully compensates for the lack of schema descriptions, making the parameter's meaning and format clear.

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 'Resolve' with a clear resource (ISO 4217 currency code) and lists the output fields (name, symbol, decimal places, countries). It explicitly differentiates from siblings by contrasting with live FX rates and naming alternative tools like country_lookup.

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 'Use when' and 'Do not use when' sections with concrete example queries. It names alternative tools (country_lookup, luhn_validate) for the exclusion cases, leaving no ambiguity about when to choose this tool.

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 provided, the description carries the burden of behavioral disclosure. It explicitly states the output format (reason phrase and short description) and positions the tool for debugging/API responses. While it doesn't explicitly mention side-effect-free read-only behavior, the wording 'Explain... by returning' implies no mutation, and the exclusions clarify boundaries. A small addition about handling unknown codes would make it 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 description is well-structured with an opening sentence, a Use when list, and a Do not use list. Every line adds value, and the formatting makes it easy for an agent to scan and apply. No filler or redundancy.

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 simple one-parameter lookup tool, the description is nearly complete. It defines the input, explains the output, and provides usage boundaries. It lacks an explicit statement of what happens for invalid/unknown codes, but the schema enforces the range and the use cases cover the primary agent scenarios. The absence of an output schema is mitigated by the description's explicit mention of the return value.

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 schema only defines 'code' as an integer 100-599 with no description. The description compensates by explaining the parameter as a 'numeric HTTP status code' with examples 404 and 429, adding meaning beyond the raw schema. It doesn't explicitly enumerate the full range, but the schema already handles that.

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 'Explain' and identifies the resource 'numeric HTTP status code'. It clearly states the tool returns the standard reason phrase and a short description, which distinguishes it from sibling lookup tools like mime_lookup.

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 provides explicit 'Use when' and 'Do not use when' sections, with concrete examples like 'What does HTTP status 404 mean?' and alternatives such as 'use mime_lookup'. This is exemplary usage guidance.

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. It discloses the core behavior (validation and normalization), but lacks details on return format, error handling, or what 'normalized' means exactly. For a validator, this is adequate but not thorough.

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 concise, front-loaded with the purpose, and structured with clear bullet lists. Every sentence adds value; no redundant or filler content.

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?

The tool is simple (1 param, no output schema), but since there is no output schema, the description should specify the return shape. It says 'return normalized digits' but not the full return structure (e.g., boolean plus normalized value). This is a meaningful gap, though the usage sections are comprehensive.

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 single parameter 'value' is described as 'ISBN-10 or ISBN-13 candidate'. The description reinforces the accepted formats but does not add substantial new meaning beyond the schema. Baseline 3 applies.

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 verb+resource: 'Verify whether an ISBN-10 or ISBN-13 passes checksum rules and return normalized digits'. It clearly distinguishes from sibling validation tools (uuid_validate, luhn_validate) by focusing on ISBN formats and explicitly naming alternatives in the 'Do not use' section.

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 includes explicit 'Use when' and 'Do not use when' sections with concrete examples, and names alternative tools (uuid_validate, luhn_validate) for other validation tasks. This gives clear decision criteria.

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 must fully disclose behavior. It mentions 'return a normalized representation when possible' but does not clarify what happens for invalid JSON (error, null, boolean?), nor the exact output format. The hedged 'when possible' adds ambiguity.

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 well-structured: a concise lead sentence followed by purposeful Use when/Do not use when bullets. No filler or redundant content.

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 simple one-parameter tool, the description covers purpose and usage guidelines well. However, since there is no output schema, the return value and error handling are left unspecified. This is a notable gap for an agent deciding how to handle results.

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 schema has 0% description coverage, so the description must compensate for the single 'value' parameter. It implies the parameter is a JSON string ('Parse a string as JSON') but does not explicitly name 'value' or discuss edge cases like whitespace or encoding. Minimal compensation.

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 clearly states the tool parses a string as JSON to confirm well-formedness and return a normalized representation. It explicitly distinguishes itself from Base64, UUID, and ISBN validation tools via the 'Do not use when' section.

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 includes explicit 'Use when' and 'Do not use when' sections, listing concrete scenarios and naming alternative tools (base64_encode/base64_decode, UUID/ISBN validators). This is exactly the guidance an agent needs.

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 provided, the description carries the full burden of behavioral disclosure. It accurately describes the input and output (English and native names), and implicitly indicates a read-only, side-effect-free operation. It does not detail error handling or edge cases, but given the simple lookup nature, this is acceptable.

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 well-structured with a concise opening purpose statement followed by bullet-style 'Use when' and 'Do not use when' sections. Every sentence earns its place, and there is no extraneous information.

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 the tool's simplicity (one parameter, no annotations, no output schema), the description fully covers the needed context: what the tool does, when to use it, what input to provide, and what output to expect. It is complete enough for an AI agent to select and invoke it correctly.

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 0%, so the description must define the parameter. It does so clearly: 'code' is an ISO 639-1 language code, with examples 'en, fr, or ja' and the constraint 'two-letter code'. This adds meaningful context beyond the raw schema, though it does not address the schema's maximum length of 3 characters.

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 clearly states the tool's function: resolving an ISO 639-1 language code to its English and native names. It distinguishes itself from siblings by explicitly listing 'do not use when' scenarios such as translation, language detection, and country language lookup, even naming country_lookup as the alternative.

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 'Use when' examples with concrete queries and 'Do not use when' exclusions, as well as naming the appropriate alternative tool for country-based lookups. This gives the AI agent clear decision criteria for when to invoke this tool.

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 provided, the description carries the full burden of behavioral disclosure. It clarifies that the tool is a pure validation step ('before accepting or storing the value'), implying no mutation or external side effects. However, it does not explicitly state the return type or how errors are handled, leaving a minor gap for a simple checksum function.

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 concise and well-structured: a leading sentence explains the core function, followed by bulleted use/do-not-use lists. Every sentence provides actionable guidance, and there is no redundant or vague wording.

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 validator with no output schema, the description covers purpose, usage context, and exclusions comprehensively. The only missing piece is an explicit statement of the return value (e.g., true/false), which would strengthen completeness given the absence of an output schema.

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% with one parameter 'value' described as 'Numeric string to validate with Luhn'. The description adds context about payment-card-like identifiers but does not introduce additional format requirements (e.g., digits only, length limits). Since the schema already documents the parameter adequately, the baseline of 3 applies.

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 ('Run the Luhn checksum') and resource ('numeric string such as a payment-card-like identifier') and explains the purpose ('verify the check digit before accepting or storing the value'). It clearly distinguishes this tool from sibling validators like isbn_validate and uuid_validate.

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 provides explicit 'Use when' and 'Do not use when' sections, naming alternative tools (isbn_validate, uuid_validate, currency_lookup) and excluding payment processing actions. This gives an agent unambiguous context for when to invoke this tool versus alternatives.

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 of behavioral disclosure. It clearly implies a read-only mapping operation ('Map... to curated metadata') and limits its scope by excluding byte sniffing, encoding, and DNS lookups. However, it does not mention error handling for unknown extensions or case sensitivity, which prevents a perfect score.

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 efficiently structured: a concise overview sentence, followed by bullet-style 'Use when' examples and a clear 'Do not use when' list. Every sentence contributes directly to decision-making, with no redundancies or filler. The front-loaded purpose sentence ensures immediate clarity.

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 low-complexity tool with one parameter, no annotations, and no output schema, the description covers all necessary decision points: what it does, when to use it, when not to use it, and what the query parameter accepts. The exclusions and alternatives provide a complete context for selection, making it sufficient for an AI agent to invoke correctly.

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 input schema only defines 'query' as a non-empty string with zero description. The description compensates by specifying that the query accepts either a file extension (e.g., 'webp', 'png') or a MIME type string (e.g., 'application/json'), with concrete examples. This adds meaning beyond the schema, though it doesn't detail formatting edge cases like leading dots or case handling.

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 first sentence clearly defines the tool: 'Map a file extension such as webp or png, or a MIME type string, to curated Content-Type metadata.' This is a specific verb+resource action that distinguishes it from sibling lookups like tld_lookup or currency_lookup. The description also states concrete use cases (setting headers, validating uploads, choosing media types), making the purpose unmistakable.

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 provides an explicit 'Use when:' section with three example queries and a 'Do not use when:' section with three exclusions, naming alternative tools (base64_encode/decode, tld_lookup). This gives the agent clear decision criteria for when to invoke this tool versus siblings, exceeding the minimum requirement.

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 provided, the description carries the full burden of behavioral disclosure. It clearly states bidirectional conversion and the API-bridging purpose, but it omits details about timezone handling and the exact output structure for 'epoch values', leaving minor ambiguity.

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 front-loaded with a concise, specific first sentence, followed by well-organized 'Use when' and 'Do not use when' lists. No sentence is wasted; all content contributes to tool selection and correct invocation.

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 simple two-parameter converter with complete schema coverage, the description adequately covers purpose, usage, and exclusions. However, since no output schema is present, the description could more precisely specify the output format for 'epoch values', preventing a perfect score.

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 input schema already documents both parameters with 100% coverage, so a baseline of 3 is appropriate. The description adds useful context about bridging API time formats but does not provide additional parameter-level details beyond what the schema already states.

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 opens with a specific conversion statement ('Convert Unix epoch seconds or milliseconds to ISO-8601, or an ISO-8601 datetime to Unix epoch values'), making the tool's function unambiguous. It also distinguishes from sibling tools via explicit 'Do not use when' examples such as timezone_convert and unit_convert.

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 provides explicit 'Use when' and 'Do not use when' sections, including named alternative tools. This gives the agent clear, actionable criteria for choosing this tool over its siblings.

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 discloses core behavior: preserving the same instant, DST-aware offsets, and interpreting naive datetimes via from_timezone. It does not mention error handling or output format, but for this tool the essential behavior is well covered.

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 concise, front-loaded with the primary purpose, and uses bullet-style sections for usage guidance. No wasted sentences; every section 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?

For a simple 3-parameter conversion tool with full schema coverage, the description provides complete context: purpose, examples, alternatives, and boundary conditions. No output schema is needed for this straightforward transformation.

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%, so parameters are fully described in structured data. The description adds examples but does not significantly enrich parameter semantics beyond what the schema already states.

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 clearly states the tool converts ISO-8601 datetimes between IANA timezones while preserving the same instant, with DST-awareness. It is distinct from siblings like timestamp_convert and unit_convert through explicit examples and exclusions.

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?

Explicit 'Use when' and 'Do not use when' sections provide clear contextual guidance, naming specific alternatives (timestamp_convert, unit_convert) and example queries that illustrate appropriate usage.

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 provided, the description carries the full burden of behavioral disclosure. It clearly states that this is a 'curated metadata' lookup, implying a static dataset and no side effects. It also explicitly excludes domain registration checks and DNS/WHOIS resolution, which helps set expectations. However, it does not mention error handling for invalid TLDs or whether TLDs with a leading dot are accepted, leaving minor gaps in transparency.

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 concise and well-structured, with a brief opening sentence, followed by 'Use when' and 'Do not use when' sections. Every sentence adds value, providing either core purpose, usage examples, or exclusions. No redundant or filler content exists, making it highly efficient for an agent to parse.

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 simple single-parameter lookup tool with no output schema, the description is complete. It defines the tool's purpose, gives clear usage examples, and lists exclusions, all in a compact format. The lack of output format details is acceptable given the simplicity of the tool and the clarity of its intended use.

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 input schema only defines a 'tld' string with minLength 2 and no description (0% schema coverage). The description compensates by providing examples like 'com, io, or ai' and using the phrase 'DNS top-level domain', which clarifies the expected format (no leading dot, not a full domain name). This adds useful semantic meaning beyond the bare schema, though it could be more explicit about punctuation.

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 clearly states the tool's function: 'Identify what a DNS top-level domain such as com, io, or ai is classified as and commonly used for.' This is a specific verb ('identify') plus a well-defined resource ('DNS top-level domain'). It also distinguishes itself from siblings by explicitly stating not to use it for MIME type lookups, which are handled by another tool.

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 provides explicit 'Use when' and 'Do not use when' sections with concrete example queries, such as 'What kind of TLD is .io?' and 'Look up MIME types for file extensions (use mime_lookup)'. This gives clear guidance on when to use this tool versus alternatives, making it easy for an agent to route correctly.

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 discloses that conversions are deterministic and restricted to length, mass, and temperature, and excludes currencies/timestamps. However, it does not mention unit format expectations (e.g., abbreviations, case sensitivity), error handling for unsupported units, or whether output is numeric, which are relevant behavioral details for an agent.

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 compact and well-structured: a clear opening sentence, a bulleted 'Use when' with three concrete examples, and a 'Do not use when' list. Every sentence contributes information without redundancy, and the use-case guidance is front-loaded.

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 straightforward conversion tool, the description covers purpose, categories, examples, and exclusions. It does not explicitly state the return format (e.g., number) or list all units, but given the lack of an output schema, these are minor gaps that do not prevent correct invocation in most common cases.

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% and there are no enums, so the description must compensate. It does so by giving examples (miles, kilometers, Celsius, Fahrenheit) and implicitly mapping '10 miles' to value, from_unit, and to_unit. However, it does not enumerate the full set of supported units or clarify input formatting (e.g., symbol vs full name, case sensitivity), leaving ambiguity for arbitrary unit strings.

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 opens with a specific verb ('Convert') and resource ('numeric value between supported length, mass, or temperature units'), provides concrete examples (miles to kilometers, Celsius to Fahrenheit), and clearly distinguishes itself from sibling conversion tools like currency_lookup, timestamp_convert, and timezone_convert by naming their scopes.

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?

Includes explicit 'Use when' and 'Do not use when' sections. It names alternative tools for excluded categories (currency_lookup for currencies, timestamp_convert/timezone_convert for time) and provides concrete user queries to illustrate appropriate usage, giving strong selection guidance.

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 provided, the description carries the full burden. It explains the main behavior and typical use cases, but does not disclose edge cases such as handling of invalid percent-encoding or whether '+' is decoded as a space. This is adequate but not deeply transparent.

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 well-organized with a main sentence and bullet-style sections. It is concise, though the 'Use when' bullet 'Decode this percent-encoded URL component' is slightly redundant with the first sentence.

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 simple one-parameter decoder, the description is complete: it states the transformation, provides concrete use cases, and explicitly lists exclusions. No output schema exists, but the plain-text result is clearly stated.

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 schema only defines a string parameter named 'value' with no description. The tool description compensates by indicating that the value is the percent-encoded URL component to decode, adding practical meaning beyond the bare 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 clearly states the tool decodes a percent-encoded URL component into plain text. It names the resource (URL component) and specific operations, and distinguishes itself from siblings like url_encode and base64_decode.

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 provides explicit 'Use when' and 'Do not use when' sections, including named alternatives (url_encode, base64_decode) and clarifies contexts like reading query parameters and path segments. This gives clear guidance on when to select this tool.

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. It discloses the encoding style (encodeURIComponent-style) and the intended purpose (URL safety). It doesn't detail edge cases or return value, but for a pure encoder this is sufficient behavioral context.

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 perfectly sized: one-sentence summary followed by short bullet lists. Every line earns its place, and the structure front-loads the core message.

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 simple one-parameter utility with no output schema, the description fully covers purpose, usage, and exclusions. No additional context is needed for an agent to select and invoke the tool correctly.

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 0%, so the description must compensate. It refers to 'this string' and 'text' in the use cases, making it clear that the single 'value' parameter is the string to encode. It adds contextual meaning beyond the schema despite not having a dedicated param description.

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 clearly states the tool applies encodeURIComponent-style percent-encoding to make strings URL-safe, with a specific verb, resource, and purpose. It distinguishes itself from siblings by explicitly naming url_decode and base64_encode as alternatives.

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 provides explicit 'Use when' and 'Do not use when' sections, listing concrete scenarios and naming the appropriate alternative tools. This is exactly the level of guidance needed.

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 provided, the description carries the full burden of behavioral disclosure. It states the core behavior and includes a useful caveat: 'when recognizable' regarding version and variant reporting, indicating that the tool may not always be able to determine these. However, it does not disclose the return format (e.g., boolean, object) or edge-case handling (e.g., nil UUID), which leaves some ambiguity. Still, the provided behavioral context is honest and non-misleading, warranting a score above 3.

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 compact and highly structured. The opening sentence states the core purpose, followed by concise bullet-point lists for use and non-use cases. Every sentence serves a purpose, with no unnecessary elaboration or repetition. It is front-loaded and immediately actionable, ideal for an agent scanning tool descriptions.

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?

This is a simple single-parameter validation tool with no output schema. The description covers the tool's purpose, usage scenarios, and exclusions, which is largely complete. The main gap is the lack of explicit return-value details (e.g., does it return a simple boolean or an object with version/variant?). However, given the tool's low complexity and the richness of the rest of the description, it is adequately complete for effective 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?

The input schema has 100% coverage for the single parameter 'value' with description 'UUID candidate string'. The description adds general context about well-formedness and version/variant but does not specify format details such as case sensitivity or canonical form beyond what the schema implies. Given the high schema coverage, the description's marginal contribution is sufficient for a baseline score of 3.

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 opens with a specific action: 'Check whether a string is a well-formed UUID and, when recognizable, report its version and variant.' This clearly identifies the resource (UUID strings) and the operations (validation + version/variant reporting). It also implicitly distinguishes itself from sibling validation tools like isbn_validate and json_validate by the explicit exclusions in the 'Do not use when' section.

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 includes dedicated 'Use when' and 'Do not use when' sections. The 'Use when' section gives concrete example questions and contexts (validating a UUID before using it as a primary key). The 'Do not use when' section explicitly names alternatives (isbn_validate, json_validate) and states when generation is not appropriate. This is exactly the level of guidance expected.

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