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

No annotations are supplied, so the description carries the full behavioral burden. It reveals that three external lookups are performed, implying a read-only, multi-step network operation, but says nothing about rate limits, authentication, or latency/cost of the aggregate call.

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 line with no filler, and the list of covered checks is compact. It is arguably too terse rather than too long, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is legitimately omitted. Still, for a tool that fans out to three subsystems, the description gives no expectations about what is aggregated or how failures in one check are handled.

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 the single required 'domain' parameter has no description anywhere. The description adds no format guidance (bare hostname vs. URL, apex vs. subdomain), which matters for a lookup that feeds whois, TLS, and HTTP checks.

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 names a specific resource (domain health) and enumerates what the aggregate covers: whois, TLS, and HTTP headers. That enumeration distinguishes it from siblings like dns_lookup or check_ip, though it never explicitly says so.

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 or when-not-to-use guidance and no sibling is named as an alternative. An agent must infer from the word 'aggregate' that this bundles several checks rather than replacing the single-purpose tools.

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 supplied, so the description carries the burden, and it does disclose real behavior: the tool inspects the caller's own egress address, returns CGNAT/shared-address classification, and that the `ip` field is currently inert. It omits anything about auth, rate limits, or whether requests are logged, which are relevant for a self-IP lookup.

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 tight sentences, front-loaded with what the tool returns and followed by the one non-obvious caveat about the `ip` parameter. Nothing is redundant or padded.

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 zero-required-argument, read-only self-lookup with an output schema present, the description covers scope, returned facets, and the inert parameter. Return-value formatting is handled by the output schema, so nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and `ip` is a bare nullable string, so the description is the only source of meaning. It explicitly explains that `ip` is reserved and non-functional today, which prevents an agent from passing a value and expecting a targeted lookup — exactly the gap the schema leaves.

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 and resource ('Check the caller's own public IP') and enumerates the returned facets: ASN, geolocation hint, and shared/CGNAT classification. The phrase 'caller's own' implicitly separates it from siblings like ip_info and ipv6_info, which appear to be arbitrary-target lookups, but no sibling is named explicitly.

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 saying `ip` is reserved for a future verified lookup, the description tells an agent to call with no arguments and to expect a self-lookup. It never says when an agent should choose this over ip_info or ipv6_info, nor what to do if it actually needs information about a specific address.

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 supplied, so the description carries the full burden, yet it discloses nothing beyond the one-line purpose. It does not say the operation is read-only, whether results are cached or rate limited, or how subdomains and missing records are handled — gaps that matter for a domain-reputation lookup.

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 and no repetition of the title. It is efficiently sized, though the brevity leaves key operational details to inference rather than structuring them explicitly.

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?

An output schema exists, so return-value explanation is rightly omitted, and the tool takes only one parameter. However, for a security-posture check the description should at least indicate scope (SPF/DMARC only) and input expectations, which it leaves unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate, but it only implies the parameter is a domain. It never clarifies whether it expects the root domain or the sending subdomain, and it ignores that 'domain' is the sole required input with an obvious format.

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 ('Check') and resource ('SPF and DMARC posture for outbound mail authentication'), which clearly separates it from generic siblings like check_domain or dns_lookup. The only shortfall is that it doesn't state what it does NOT cover (e.g. DKIM), so the boundary against dns_lookup is inferred 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?

There is no when-to-use guidance and no mention of the sibling tools it overlaps with, notably dns_lookup and check_domain. An agent must guess whether this composite mail-auth check supersedes a raw DNS TXT lookup or supplements it.

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

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

With no annotations, the description carries the full behavioral burden and does well: read-only probing, no tool invocation, the private-target refusal policy and its hosted-endpoint exception are all stated. Gaps remain around rate limits, timeouts, and how failures are reported, which for a network-probing tool would be helpful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, then the enumerated checks, then the parameter caveat. Dense and mostly waste-free, though the backtick-laden parenthesis about allow_private is a single long sentence that takes effort 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?

An output schema exists, so return-value description is not required, and both parameters plus the safety boundary are covered. For a two-parameter probe tool this is nearly complete; operational details like timeouts are the only meaningful omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does: `url` is scoped to an MCP server endpoint, and `allow_private` is explained with its default, its intent (CI use only), and an override condition. Only the URL format/expected scheme is left unstated.

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 and resource ('Probe an MCP server endpoint for anonymous access') and then enumerates exactly what is checked: initialize/tools/list without credentials, auth/OAuth discovery, TLS, and dangerous-looking tool names. An agent can immediately tell this apart from the DNS/IP/report siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear use condition (anonymous-access probing of an MCP endpoint) and an explicit boundary ('Never calls a tool'), plus a concrete when-not for allow_private (refused by default, always refused on the public hosted endpoint). It does not explicitly compare against siblings, but the sibling set is unrelated enough that this costs little.

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 supplied, so the description carries the full disclosure burden. It does add meaningful context beyond the name by stating the ownership-verification gate, which is exactly the kind of precondition an agent needs. However, it says nothing about whether this is an active/intrusive scan, which ports are probed, expected duration, or rate limits — significant gaps for a network-probing operation.

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 short sentences with zero filler, and the safety constraint is front-loaded so an agent reading only the first line still gets the ownership requirement. Nothing is repeated from the tool name.

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?

An output schema exists, so return-value explanation is legitimately omitted, and the ownership gate covers the most important policy dimension. What remains missing for a single-target network probe is the operational profile: scan intensity, whether it is detectable by the target, and acceptable target formats. Adequate but noticeably thin for a security-sensitive tool with no annotations.

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 required parameter, 'target', with 0% schema description coverage, so the description must compensate and it largely does not. It never clarifies whether the target is an IP address, hostname, URL, or CIDR range, nor what format is accepted. The only semantic added ('a target you have verified you own') describes a policy condition, not the parameter's value shape.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Check commonly-exposed device ports on a target'. This is clearly distinguishable from siblings like check_ip, check_domain, or subnet_calc, which address different resources. It stops short of explicitly naming a sibling it should be preferred over, so it is clear but not maximally differentiating.

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?

Gives an explicit precondition and an explicit exclusion: the target must be one 'you have verified you own', and the tool is 'never an unverified scan'. That is a real when/when-not rule. It does not point to an alternative tool for unverified targets, so the routing guidance is incomplete rather than absent.

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 behavioral burden. It discloses the supported lookup types, which is valuable, but it does not explicitly state that the operation is read-only, whether it queries public DNS, or how errors are handled. The 'lookup' verb strongly implies safety, but does not formally declare it.

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 front-loaded. Every sentence adds useful information, especially the enumeration of valid DNS record types, and there is no unnecessary 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 simple two-parameter lookup tool with an output schema, the description is nearly complete. It provides the critical enum values for `type`, and return values are covered by the output schema. The main remaining gap is the lack of explicit `name` format guidance and usage exclusions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It fully compensates for the `type` parameter by enumerating all allowed values, but it adds no detail about the `name` parameter—such as whether it should be an FQDN, hostname, or IP for PTR lookups.

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 and resource: 'DNS lookup for a name.' This clearly identifies the tool's operation, but it does not explicitly distinguish it from related siblings such as check_domain or ip_info.

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 name and description—this is the tool for resolving DNS records for a given name. However, there is no explicit when-to-use guidance, no exclusions, and no comparison to alternatives like check_domain.

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

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

With no annotations, the description carries the full behavioral burden. 'Get' implies read-only access and 'AI-generated, citation-backed' describes how the explanation is produced, but it does not state permissions, whether the saved report is modified or regenerated, latency/cost, or failure behavior.

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 with no wasted wording. It states the essential action and output type immediately.

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 tool with an output schema, the description covers purpose and output nature. However, with no annotations it should clarify read-only behavior and the report_id prerequisite, leaving the definition only adequate overall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema only names report_id without format or source details. The description adds that the ID refers to a previously saved AdminKit report, but it does not explain how to obtain the ID, its expected format, or what happens with an invalid ID.

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 and output ('Get an AI-generated, citation-backed explanation') for a specific resource ('a previously saved AdminKit report'). It is clear enough to distinguish from the unrelated network/diagnostic siblings, though it does not explicitly position itself against any 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?

It implies use only when a report has already been saved and a report_id exists, but gives no explicit when-not-to-use guidance, prerequisites, or alternative behavior if the report is missing. Adequate but minimal.

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

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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful behavioral fact: results are only ever aggregated across >=5 tenants, so no per-tenant drill-down is possible. It says nothing about authentication, rate limits, data freshness, or the time window of the trends.

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 short sentences, with the core purpose front-loaded and the privacy constraint immediately after. No filler or restatement of the tool name.

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-optional-parameter tool with an output schema, the description covers purpose, the valid protocol values, and the aggregation floor. The only notable gap is the null/omitted-protocol behavior and the temporal scope of the trend data.

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% and the schema defines 'protocol' as a bare string with a null default, so the description is the only place the accepted values (mqtt, modbus, mcp, rtsp, telnet, dns) appear — that is meaningful compensation. It does not explain what omitting the parameter or passing null does, which leaves one real ambiguity.

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 and resource ('Get aggregated honeypot/telemetry trend data') plus the domain it applies to, which is enough to separate it from the per-indicator check/lookup siblings such as check_ip and dns_lookup. It stops short of saying what the trend actually measures or over what window, so the picture is clear but not fully precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use statement versus alternatives, but usage is implied by the aggregation constraint: it is the tool for cross-tenant trend views rather than single-indicator lookups. An agent must infer that routing decision itself.

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 supplied, so the description carries the full burden. "Pure address math, not a lookup" usefully signals a local, side-effect-free computation with no network call or rate limit, but it says nothing about behavior on malformed input (error vs. null) or whether the address is normalized before inspection.

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 output content is front-loaded and the disambiguating scope statement follows immediately, so an agent gets the essential facts in one pass.

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?

An output schema exists, so return values need not be explained, and the description covers purpose, scope, and input domain for a one-parameter tool. The remaining gap is invalid-input handling, which is minor for a stateless computation.

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 the single "ip" property is an undescribed string, so the description must compensate. It does partially, by making clear both IPv4 and IPv6 literals are accepted, but it gives no guidance on accepted formats (CIDR suffix, zone IDs, leading zeros) or rejection behavior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb ("Inspect") and resource ("any IPv4 or IPv6 address") and enumerates exactly what is reported: version, private/global/loopback/link-local/multicast/reserved flags, decimal integer form, and compressed/exploded notation. It separates itself from owner-lookup siblings (check_ip, dns_lookup) with "not a lookup against the address's owner," though it never distinguishes itself from the near-overlapping ipv6_info.

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 clause "Pure address math, not a lookup against the address's owner" gives an explicit when-not boundary that steers agents away from DNS/ownership tools toward this one. It stops short of naming the alternative to use instead, so routing for the IPv4-vs-IPv6 split against ipv6_info is left to inference.

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 supplied, the description carries the full behavioral burden; it does well on the operational side by disclosing that everything is computed locally with no queries, which implies determinism and no rate limits. It is silent on what happens for malformed or non-IPv6 input and does not restate that the operation is a pure read, leaving gaps for a tool with zero annotation coverage.

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 tightly packed sentence that front-loads the verb and the main output, then lists the derived artifacts and closes with the local-computation guarantee. Nothing is redundant and no filler appears.

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?

An output schema exists, so return values need not be explained, and the description covers what is computed and that no external lookup occurs. The main omission is input validation behavior, which is minor for a simple single-parameter inspection 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 description coverage is 0% for the single 'ip' parameter, so the description must compensate. It does convey the key constraint that the value is an IPv6 address by naming the tool's subject, but adds no expected format, prefix-length handling, or how non-IPv6 values are rejected.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Inspect an IPv6 address in depth') and enumerates the concrete outputs: /64 network, reverse-pointer form, embedded IPv4 forms. It does not, however, distinguish itself from the sibling ip_info, which an agent could easily confuse it with.

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 phrase 'derived locally, nothing is queried' implicitly signals that this is the right choice when no network resolution is desired, contrasting with dns_lookup. But it never names an alternative or states explicitly when to prefer ip_info over this tool, leaving the choice for IPv4 vs IPv6 inputs and general-vs-deep inspection to inference.

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 present, the description carries the full burden, and it does disclose two genuinely useful traits: the lookup is against a 'bundled IEEE registry snapshot' (offline, snapshot-bounded coverage) and it 'returns found=false honestly if unmatched' (non-error empty-result semantics). It omits format normalization (separators, case sensitivity), whether OUI-only prefixes are accepted with or without punctuation, and what the snapshot's currency means for misses.

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 waste, with the operation and accepted input forms front-loaded and the data-source caveat attached immediately after. Nothing in it is redundant with the name or the 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?

This is a single-parameter read-only lookup and an output schema exists, so return-value explanation is not required. Covering what it looks up, the source of truth, the accepted input forms, and the not-found behavior leaves no material gap for correct 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?

Schema description coverage is 0% and the single parameter 'mac' carries no schema description, so the description must compensate. It does, by defining the accepted value domain: a full MAC-48 address or a bare OUI prefix, which tells the agent what to put in 'mac' rather than passing an arbitrary string.

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 plus resource: 'look up the registered vendor for a MAC-48 address or bare OUI prefix'. The resource domain (MAC/OUI) is distinct from every listed sibling (check_ip, dns_lookup, subnet_calc, etc.), so an agent can tell it apart without opening the schema, though no sibling is named explicitly.

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 context is implied by the accepted input forms ('MAC-48 address or bare OUI prefix') and the data source named, but there is no explicit when-to-use statement, no when-not-to-use, and no routing to an alternative when the input is an IP address or hostname. The agent must infer that this is the right tool for MAC lookups.

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 supplied, so the description carries the full behavioral burden. It does disclose the shape of the computed result and implies a pure read-only calculation with no side effects, but it never states that this is a local/deterministic computation, what happens with a malformed CIDR, or whether host bits are normalized.

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 sentence, front-loaded with the verb and resource, then the concrete outputs. No filler, no repetition of the tool name, and the enumerated return values make the payload immediately 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?

An output schema exists, so return values need not be spelled out, and the tool is a simple one-parameter computation, which the description covers well. The remaining gap is error/edge-case behavior for invalid CIDR input, which is minor for this tool class.

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% for the single required parameter, so the description must compensate. Saying 'for a CIDR' establishes the expected format (address/prefix), which is real added meaning, but it omits examples, accepted prefix ranges, and whether bare addresses or host-bit-set CIDRs are tolerated.

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?

Uses a specific verb ('Calculate') with a specific resource ('IPv4/IPv6 subnet details for a CIDR') and enumerates the outputs: network/broadcast/netmask, usable host range and count, and address-class flags. This is unmistakably distinct from every sibling (check_ip, ip_info, ipv6_info, dns_lookup), none of which perform subnet arithmetic.

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 it should call this when it has a CIDR and needs derived subnet values. There is no explicit when-to-use statement, no mention of how it relates to ip_info/ipv6_info (which return address metadata rather than subnet math), and no note on prerequisites or input validity.

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 at all, the description carries the full behavioral burden. It does disclose one genuinely useful trait — unmatched fields return null rather than being guessed — which tells the agent how to interpret partial results. It does not state that the operation is a pure/side-effect-free read, how malformed or empty input is handled, or any rate/size constraints, so the safety profile remains undisclosed.

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 short sentences, front-loaded with the core action and output list, followed by the one caveat that matters. No filler, no restating of the tool name, nothing that could be cut.

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?

An output schema exists, so return values need not be spelled out, and the description still summarizes the result shape and the null behavior. For a one-parameter pure parser this is nearly complete; only input-format expectations and failure behavior on invalid input are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single parameter is named only "ua", so the description has to compensate. Saying "Parse a User-Agent string" does establish that the input is a raw UA string, but it adds no format expectations (e.g. full header value, examples, whether it may be empty), leaving the parameter only partially documented.

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 and resource ("Parse a User-Agent string") and enumerates the outputs (browser, OS, device family/version, bot flag), so the agent knows exactly what this does. None of the siblings (check_ip, dns_lookup, mac_vendor, etc.) parse UA strings, so the purpose is unambiguous in context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives. Usage is only implied by the tool name and the word "Parse" — an agent must infer that it should supply a raw UA header value rather than, say, a device ID. For a single-purpose utility this is tolerable but 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.