Stackhal

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network-touching behavior are covered. The description usefully scopes what is examined, but says nothing about whether it fetches live content, how long it takes, or what the report contains.

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 sentence, front-loaded with the verb and resource, with the parenthetical list earning its space by previewing the analysis dimensions. Slightly dense but free of 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?

Adequate for a single-URL read-only analyzer, but with no output schema the description never hints at the shape or depth of the result (scores, findings, pass/fail), leaving an agent to guess at return values.

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?

Only one parameter, and schema description coverage is 100%, so the schema fully documents 'url'. The description adds no format or constraint detail beyond what the schema already provides, which is the expected baseline here.

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 ('Analyze') and resource ('GEO signals and AI crawler readiness for a web page'), then enumerates the signal families it inspects (schema, citations, provenance, answer structure, llms.txt, robots rules). This clearly separates it from the SEO-flavored sibling audit_website_seo, though the contrast is implied rather than stated.

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 only implied by 'for a web page'. There is no statement of when to reach for this tool versus audit_website_seo, no prerequisites, and no exclusions (e.g., single page vs whole site).

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral value beyond them: 'deterministic' signals repeatable results, and the checklist tells the agent what the tool actually fetches and inspects. It stops short of disclosing latency, request volume, or timeout behavior for a live-crawl 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?

Two sentences, zero filler. The core action and scope come first, with the check list as supporting detail. Nothing reads as redundant.

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 enumerated checks usefully stand in for describing what the audit returns, and annotations cover the read-only/open-world profile. The remaining gap is operational: nothing says how long the audit takes, whether it is synchronous, or what happens on an unreachable URL.

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?

Only one parameter and schema description coverage is 100%, so the schema documents 'url' fully with an example. The description still adds semantics the schema does not: the URL must be a *public* website, implying private, internal, or credentialed URLs are out of scope.

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 ('Run') and resource ('technical SEO audit') scoped to 'a public website URL', then enumerates exactly what is inspected (canonicals, title tags, robots.txt, redirects, crawl traps, indexability). No sibling tool covers SEO, so the agent can route here unambiguously.

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 'public website URL' constraint, which tells the agent this is not for authenticated or private pages, but there is no explicit when-to-use guidance, no statement of prerequisites, and no alternatives to consider. Adequate but thin.

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?

Annotations declare readOnlyHint=true and openWorldHint=false, covering the safety and scope profile. The description adds functional details but no additional behavioral traits like performance, limits, or side effects; with annotations present, this is adequate.

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?

Single sentence, front-loaded with the verb and resource, with zero filler. Efficient and well-structured for an agent scanning tool options.

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?

No output schema exists, yet the description does not explain the return format or structure of results. It covers what analyses are performed, which partially compensates, but an agent still lacks clarity on what to expect back.

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 100%, so all three parameters are fully documented in the schema. The description mentions 'free subnet allocation' and 'parent range' but adds no syntax or format beyond the schema, so 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?

States a specific verb 'Analyze' and resource 'IPv4/IPv6 CIDR subnets', and enumerates the four analysis outputs (collisions, containment, bit-tree partition, free allocation). Siblings are unrelated, so no differentiation is needed. An agent can immediately tell this is a CIDR range analysis 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?

Provides implied usage by listing the analysis types, but gives no explicit when-to-use, prerequisites, or exclusions. There are no similar siblings to distinguish from, so guidance is minimal but not misleading.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral value by naming the four diagnostic categories it evaluates, telling the agent what findings to expect, though it omits how results are returned or whether it mutates nothing beyond reading input.

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?

One dense sentence, front-loaded with the verb and resource, then the enumerated checks in priority order. No filler or restatement of the title.

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 read-only, three-parameter diagnostic with no output schema and fully documented parameters, the description gives enough to invoke correctly. Only a hint about the shape of the returned report is missing, which is minor.

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 100%, including format examples (Origin URL string, key-value map or "Header: Value" list) and the credentials flag default. The description adds no parameter-level meaning beyond the schema, so the 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?

States a specific verb (Analyze) and resource (CORS request/response headers) and enumerates the exact classes of findings it produces: wildcard/credential violations, missing Vary: Origin, preflight OPTIONS handling, header exposure. No sibling tool covers CORS, so it is unambiguous against the list.

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 input shape (you supply an Origin and response headers), but there is no explicit statement of when to reach for this tool or what it does not cover, e.g. no mention of whether it can be used for preflight-only debugging or server-config auditing.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered elsewhere. The description adds only the vague qualifiers 'production-ready' and 'fully compliant', without stating what validation is performed, what the caller receives back (raw pass.json text vs. an object), or whether required Apple fields are auto-filled. With no output schema, this leaves real behavioral questions unanswered.

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 well-formed sentence with the key action front-loaded and no filler. It is dense and readable; the only mild waste is the stacked marketing adjectives 'production-ready, fully compliant'.

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 12-parameter generator with no output schema, the description at least identifies the artifact produced (pass.json specification) and the main input categories, which is minimally adequate. It stops short of describing the return shape or which Apple-required fields the caller must supply versus which are generated.

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 100%, so every parameter is already documented in the schema itself, including formats and examples. The description's list of input categories adds no syntax, defaults, or constraints beyond that, so the 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 gives a specific verb+resource ('Generate ... Apple Wallet pass.json specification') and lists the input dimensions (pass type, metadata, colors, barcode, field values). It does not explicitly name or differentiate itself from the sibling tools inspect_apple_pkpass and repair_apple_pkpass_spec, but the generate/repair/inspect distinction is inferable from the verb.

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 when-to-use guidance, no prerequisite context, and no mention of the alternatives (repair_apple_pkpass_spec for fixing an existing spec, inspect_apple_pkpass for reading one). The trailing phrase 'based on pass type, metadata, colors, barcode, and field values' describes inputs, not usage conditions.

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?

Annotations declare readOnlyHint=true and openWorldHint=false, so the safety profile is already covered, and the description usefully expands on what the bundle contains (adaptive dark-mode SVG, multi-resolution ICO, webmanifest). However, with readOnlyHint=true it never clarifies whether artifacts are written to disk or returned inline, nor the output shape or any size limits — meaningful ambiguity for a generator.

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 dense sentence that front-loads the verb and resource and then enumerates outputs; no filler, nothing redundant with the title.

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 while the description lists the produced artifacts (which partly compensates), it omits the return mechanism (inline files, URLs, or written paths) and any constraints, leaving a gap for a tool whose entire purpose is producing multiple output files.

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 both parameters are already documented, making 3 the baseline. The description adds a hint that dark mode is handled adaptively, loosely reinforcing dark_mode_strategy, but it does not explain the strategy values or their trade-offs.

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 ('Generate') plus a precisely scoped resource ('multi-platform favicon bundle'), with the actual artifacts enumerated (SVG, ICO, Apple Touch Icon, PWA icons, webmanifest, HTML tags) and the input type stated. No sibling tool touches favicons, so the distinction is unambiguous.

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 rather than stated: an agent can infer you call this when you need a favicon bundle, but there is no when-to-use/when-not guidance or workflow context (e.g., use after generating a logo SVG). Additionally, the description says input can be 'SVG or image input' while the schema accepts only raw SVG XML markup, a small inconsistency.

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?

Annotations already establish the safety profile (readOnlyHint=true, openWorldHint=false), so the operation is known to be a safe local read. The description usefully lists the validation dimensions (required keys, dates, ISO 8601 timezones, transit types, barcodes, color contrast), but says nothing about how failures are reported or what the result looks like.

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, front-loaded sentence with the verb first and a colon-delimited list of checks. Efficient with no filler; the only minor cost is the dense enumeration of checks.

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 read-only, one-parameter inspector, the description covers purpose, input scope, and validation breadth, and annotations cover the safety profile. With no output schema, the return shape of the validation result is the one unexplained 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?

Schema coverage is 100% and the single pass_json parameter is fully documented in the schema, so the baseline is 3. The description adds only mild value by noting it can take pass.json or package manifests, without format or edge-case detail 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?

States a specific verb (inspect and validate) and resource (Apple Wallet .pkpass JSON structure / pass.json or package manifests), and enumerates exactly what it checks. The verb also implicitly separates it from generate/repair siblings, but no sibling is named explicitly, so it stops short of a 5.

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 only implied: an agent can infer you'd call this when you have a pass.json to check. There is no explicit when-to-use, no when-not, and no routing to alternatives like repair_apple_pkpass_spec (for fixing) or generate_apple_pkpass_spec (for creating).

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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-network behavior are covered. The description adds useful scope by naming the protocols inspected, but it does not disclose return format, rate limits, or operational behavior beyond what the annotations and title provide.

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 a single, front-loaded sentence that efficiently names the action and enumerates the standards. Every clause contributes specific scope without 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 read-only, single-parameter inspection tool with no output schema, the description gives enough context to invoke it correctly and understand its scope. It could be more complete by hinting at the nature of the returned report or when to prefer it over related DNS tools, but the core invocation needs are met.

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?

There is one parameter ('domain') and schema description coverage is 100%, so the schema already documents it fully. The description adds no syntax, format, or constraint details beyond the schema, making the baseline 3 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 uses a specific verb ('Inspect') and resource ('domain email security and deliverability standards'), then enumerates the exact protocols checked (DMARC, BIMI, MTA-STS, SMTP TLS-RPT, SPF, MX). This distinguishes it from sibling tools like trace_dns_delegation and diagnose_cors_policy, which cover different domains.

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 implies the tool is used for email-security and deliverability checks on a domain, but it does not explicitly state when to choose this over alternatives or any prerequisites/exclusions. Usage is inferable from the listed standards, matching the 'implied usage' level.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, lowering the burden. The description enumerates specific repair operations, which adds functional context, but omits behavioral details like return format, idempotency, error handling, or authentication requirements.

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 front-loaded sentence states the action and then itemizes the fixes with a colon-list; every clause carries information. 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?

With no output schema and one input parameter, the description should ideally state what is returned (e.g., a repaired JSON string) and whether the input is returned unchanged on failure. It covers the repair operations well but leaves return semantics implicit.

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 fully documents the single parameter (pass_json) with a clear description. The tool description does not add any syntax or format details beyond what the schema provides, so the baseline of 3 for high schema coverage 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 ('repair and sanitize') on a clear resource ('Apple Wallet pass.json manifests') and lists the exact defects addressed. It does not explicitly reference sibling tools like generate_apple_pkpass_spec or inspect_apple_pkpass, so the differentiation is implicit rather than stated.

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?

No when-to-use or when-not-to-use guidance is provided; the description only states what the tool does. It does not name alternatives (e.g., generate_apple_pkpass_spec) or prerequisites such as 'use this after generation yields invalid pass.json'.

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and network scope are covered. The word 'live' usefully signals a real-time, non-cached lookup, but nothing is said about timeouts, rate limits, or failure behavior on unresolvable domains.

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 front-loaded sentence with no filler; the action and the object of inspection come first. Nothing could be trimmed without losing meaning.

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 read-only DNS query with no output schema, the description should at least outline what the trace returns (e.g. the delegation chain of NS records). It gestures at nameservers but leaves the return shape entirely unspecified, which the missing output schema would otherwise have carried.

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 both parameters are fully documented in the schema, including the query_type enum values. The description adds no format or syntax detail beyond that, so the 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?

States a specific verb (Query) and resource (live DNS records) plus an inspection target (authoritative nameservers), so the function is clear. However, it does not distinguish itself from the closest sibling, inspect_domain_security, so an agent still has to guess which one applies.

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 says what the tool does but never states when to use it, when not to, or which sibling to prefer. With inspect_domain_security in the sibling list, the absence of routing guidance 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?

Annotations declare readOnlyHint=true and openWorldHint=false, so safety is already covered. The description adds real value beyond them by disclosing that the tool also performs compatibility checks and ReDoS safety analysis, which tells an agent to expect diagnostic output rather than a bare converted string.

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 front-loaded sentence with no filler; every clause (engines, compatibility checks, ReDoS analysis) carries distinct 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 3-parameter, read-only tool with full schema coverage and no output schema, the description is nearly sufficient — it names the engines and the two analysis behaviors. It stops short of saying anything about the shape or content of the result, which an agent would benefit from given there is no 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% and each parameter carries its own engine-list description, so the schema does the heavy lifting. The description repeats the engine names but adds no dialect-specific syntax or defaults beyond what is already documented; 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?

States specific verbs (transpile and analyze) plus the resource (regular expressions) and enumerates the exact engines involved. Nothing among the siblings touches regex, and the scope is unambiguous.

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 implied use case — moving a pattern from one engine's dialect to another — is clear from the engine list, but the description never states when to use this versus, say, a plain analyzer, nor any prerequisites (e.g., that source_engine must match the dialect actually in use).

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?

Annotations already establish this is a read-only, non-open-world operation, so the safety profile is covered. The description adds one genuine behavioral detail — the output includes 'migration advisories' — but omits the things an agent most needs for a transpiler: fidelity limits, unsupported constructs, or whether the result is a partial/best-effort conversion.

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 front-loaded sentence naming the source, the target, and the extra output. It is efficient, though the parenthetical format enumerations duplicate the schema and could be trimmed.

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 does name the primary return artifact (Caddyfile) and the accompanying migration advisories, which is enough to set expectations for a read-only transform. It stops short of describing output shape or conversion-fidelity caveats, which would matter for a migration tool.

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 schema already documents both parameters, including auto-detection of server_type and the accepted config_content formats. The description's format list largely restates the schema, so the baseline 3 is appropriate rather than a higher score.

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 (transpile) plus both source resources (Nginx/Apache config) and the target artifact (Caddyfile), with concrete file forms named. An agent can distinguish this from every sibling, including the superficially similar transpile_regex_engine, without opening a 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?

Usage is only implied: the accepted input forms (nginx.conf, server blocks, .htaccess, VirtualHost) make it obvious when the tool applies, but there is no explicit when-to-use, when-not-to-use, or prerequisite (e.g. that this is a one-way conversion, or what to do with unsupported directives).

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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe, network-touching read. The description adds which artifacts and rules are checked, which is useful scope context, but says nothing about fetch behavior, failure modes, or whether missing files are reported as errors versus warnings.

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 front-loaded sentence that enumerates the checked artifacts without filler. Slightly list-like, but every clause carries information and nothing is repeated from the name or schema.

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 read-only two-parameter inspector the description covers the validation scope adequately, but with no output schema it does not indicate what the result looks like (pass/fail per check, diagnostics, etc.), leaving a real gap for an agent deciding how to consume the response.

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 100%, so both 'domain' and 'test_url' are already documented in the schema, including the AASA/exclusion routing purpose of test_url. The description adds no parameter-level detail beyond that, so 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?

States a specific verb (inspect and validate) plus the exact resources (Apple AASA and Android assetlinks.json files, HTTPS hosting rules, URL path routing). No sibling tool covers universal/app link validation, so it is unambiguously distinguishable from the rest of the list.

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 purpose implies when to use it, but there is no explicit when/when-not guidance, no mention of alternatives (e.g. inspect_domain_security), and no statement about prerequisites such as needing a live reachable domain. Usage is inferable but not spelled out.

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