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

No annotations are provided, and the description discloses no behavioral traits beyond the core action. It does not mention permissions, idempotency, or side effects, leaving the agent underinformed for a mutating 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?

The description is a single purpose statement followed by a concise parameter list—no wasted words.

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?

While the parameter list covers all arguments and an output schema exists, the tool lacks usage guidance and behavioral transparency, making it only partially complete for a create operation.

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 description adds meaning to all five parameters with examples for subnet and mask, and indicates optionality for description and vlan_id, compensating for the schema's lack of descriptions (0% coverage).

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 'Create a new subnet in phpIPAM' with a specific verb and resource, making it distinct from sibling tools like update_subnet and delete_subnet.

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 guidance is given on when to use this tool versus alternatives, prerequisites, or constraints. The description simply states the action without context.

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 description only states 'Delete/release' without disclosing any behavioral traits such as irreversibility, required permissions, or potential side effects. Since no annotations are provided, the description fails to convey the destructive nature beyond the verb itself.

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 extremely concise, consisting of one sentence and a brief Args section. Every word earns its place, with no redundancy or fluff, and the action 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?

Even with an output schema present, the description lacks essential context for a delete operation. It does not explain reversibility, success/failure conditions, or any impact on associated resources. The minimal information is insufficient for an agent to fully anticipate behavior.

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 description repeats the parameter name `address_id` and provides a tautological explanation ('ID of the IP address to delete') that essentially restates the parameter name. It does not specify the ID format, how to obtain it, or any additional context beyond the schema, which has no description for the property.

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 'Delete/release' as a specific verb and 'IP address reservation' as the resource, clearly distinguishing it from siblings like `delete_subnet` or `update_ip_address`. It directly states what the tool does without ambiguity.

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 guidance is provided on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or related tools like `reserve_ip_address` or `delete_subnet`, leaving the agent without context for 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?

The description includes a prominent warning that deleting a subnet deletes all IP addresses, which is a critical behavioral trait. However, it does not disclose permissions required, reversibility, or error behavior. Since no annotations exist, this warning carries much of the behavioral burden but is incomplete.

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 two sentences plus a three-line Args block. It front-loads the core action and warning, with no wasted words. The structure is clear, scannable, and appropriately sized for the tool's simplicity.

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 delete tool with an output schema, the description provides the essential action and the most important side effect. It does not explain preconditions or error handling, but the destructive cascade is prominently disclosed, making it sufficient for basic 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 Args section restates the schema parameter with a minimal gloss: 'ID of the subnet to delete.' With schema description coverage at 0%, this adds a little clarity but no format, lookup guidance, or constraints beyond what the parameter title implies. It barely compensates for the schema's lack of 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 states 'Delete a subnet' with a clear verb and resource, and the warning clarifies the scope by noting it deletes all IP addresses. This distinguishes it from sibling tools like delete_ip_address and update_subnet.

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 guidance is provided on when to use this tool versus alternatives. There is no mention of preconditions, scenarios that warrant deletion, or why an agent should choose this over update_subnet or other related tools. The warning implies caution but does not offer decision-making 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?

With no annotations, the description carries the transparency burden. It discloses the default 20-result limit, the 1000 maximum limit, and the default of essential-only fields in include_fields, which goes beyond the schema. It does not discuss errors, auth, or read-only status, but the get verb and limit details provide adequate 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 compact and front-loaded: a one-sentence purpose, a short context note, and a structured Args list. Each line contributes information, and the organization supports both skimming and reference.

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 no explanation. The description covers all parameters, defaults, and limits, and includes a performance note. It stops short of listing concrete examples or pagination semantics, but is complete enough for a list operation.

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 Args block must compensate. It provides semantic definitions for all four parameters, including defaults and the max for limit, and clarifies that include_fields is comma-separated. This adds real meaning beyond the bare schemas.

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 opening sentence, 'Get subnets within a specific section,' uses a specific verb and resource, and the 'specific section' qualifier distinguishes it from global subnet search and sibling tools such as search_subnets or get_subnet_details. The purpose is unambiguous and not a tautology.

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 when to use the tool—when subnets are needed for a given section—but provides no explicit guidance on choosing among siblings, such as search_subnets for cross-section queries. The 'CONTEXT OPTIMIZATION' note addresses output size rather than tool selection.

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 of behavioral disclosure. It adds one valuable behavior: address listing is limited to 10 by default ('CONTEXT OPTIMIZATION'). However, it does not explicitly state that the operation is read-only or describe error/edge-case behavior, leaving some transparency gap.

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 with a clear summary, followed by a prominent context note and an Args block. The Args section somewhat duplicates schema metadata, but it is justified here because the schema lacks parameter 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?

For a simple read-style tool with an output schema present, the description covers the tool's purpose, key default behavior (address limit), and all parameters. It lacks explicit alternative-tool guidance, but the sibling list provides enough context for a capable agent to select 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?

Schema description coverage is 0%, so the description fully compensates by explaining each parameter in plain language. It clarifies the conditional relationship between include_addresses and address_limit (address_limit only applies when include_addresses=True), which the schema's titles and defaults do not convey.

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 opening sentence uses a specific verb and resource ('Get detailed information about a specific subnet'), clearly indicating this tool targets one subnet by ID. It is distinct from sibling list/search/subnet tools by scope, but does not explicitly contrast itself with them.

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 usage context: call this when you have a subnet_id and want details for that specific subnet. It gives no explicit guidance about when to prefer this over get_section_subnets or search_subnets, and no exclusion 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 present, so the description carries the full burden. It does disclose a behavioral trait beyond the schema: 'Limited to 20 results by default' and a max of 1000 via the limit parameter. However, it does not discuss auth, output format, pagination behavior, or error cases.

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 with the purpose. The context note and parameter explanation are direct and contain no 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 simple list operation with one optional parameter and an output schema, the description is largely complete. The only meaningful gap is the absence of guidance relative to sibling list tools, but correct invocation is fully supported.

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 description fully compensates by defining limit as 'Maximum number of locations to return' with both a default and a maximum. This adds real meaning beyond the bare input 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 and resource: 'List physical locations from phpIPAM.' The resource 'locations' clearly distinguishes it from sibling list tools such as list_sections, list_nameservers, list_vlans, and list_vrfs.

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 guidance is provided about when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or why list_locations would be preferred over related list tools. Usage is only implied by the name and description.

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?

There are no annotations, so the description carries the full behavioral burden. It discloses the default result cap ('Limited to 20 results by default') and the max value of 1000, but it does not mention authentication needs, rate limits, or any other behavioral constraints. For a simple read-only list tool this is adequate but not rich.

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 short and front-loads the core purpose. The 'CONTEXT OPTIMIZATION' line adds useful limit information, though it is slightly redundant with the following Args block, and the label itself is not necessary.

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 low complexity (one optional parameter) and the presence of an output schema, the description is mostly complete. The main gap is the absence of usage guidance and any mention of access requirements, but for a straightforward listing tool this is acceptable.

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 for the undocumented parameter. It fully explains 'limit' as the maximum number of nameservers to return, including its default and maximum value, which goes beyond the bare schema definition.

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 a specific action ('List') and resource ('DNS nameservers') with a source ('phpIPAM'). None of the sibling tools target nameservers, so this description unambiguously distinguishes the 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?

No guidance is given about when to use this tool versus alternatives, prerequisites, or situations where another tool would be more appropriate. The description only restates the purpose and the limit parameter, leaving usage routing entirely to the agent.

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?

Since no annotations are provided, the description carries the full burden. It discloses a key behavioral trait: 'Returns essential fields only by default' and how to request complete data. This is beyond what the schema alone conveys, though it omits other details like authentication or pagination, which are less critical for a read-only list 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?

The description is concise, with the purpose stated upfront, followed by a clear 'CONTEXT OPTIMIZATION' note and a brief parameter explanation. Every sentence adds value without fluff, making it well-structured for quick reading.

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 optional parameter) and the presence of an output schema, the description covers the essential aspects: what it lists, the default field behavior, and how to get all fields. It could be slightly more detailed about what 'essential fields' are, but overall it is sufficiently complete for an agent to 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?

The schema only defines include_fields as a string with no description (0% coverage). The description adds meaning by explaining it accepts comma-separated fields, defaults to essential fields only, and can be set to 'all' for complete data. This is essential context for using the parameter correctly.

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 'List all IP sections from phpIPAM', which is a specific verb+resource with a clear scope (all sections). This distinguishes it from sibling tools like list_vlans, list_vrfs, and list_locations, which target different resources.

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 the tool's purpose but does not explicitly state when to use it over alternatives such as get_section_subnets or search_subnets. It gives guidance on the include_fields parameter ('Use include_fields="all" for complete data') but no direct comparison or exclusion statements.

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 adds a key constraint beyond the schema: 'Limited to 20 results by default' and 'max: 1000' in the Args section. This is useful behavioral context. However, it does not explicitly state that the operation is read-only, mention any authentication or rate-limit requirements, or describe ordering/pagination behavior beyond the limit. The limit disclosure earns a 3 but is not comprehensive.

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 one-line purpose, a behavioral note, and a parameter list. Every sentence adds value — the limit constraint is important, and the parameter definitions are precise. No fluff 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?

Given the tool has only two optional parameters and an output schema exists (so return values need not be described), the description covers purpose, parameters, and the key default limit. It is slightly incomplete because it lacks usage guidance (when to choose this over search_subnets, for example) and does not state whether the list is system-wide or scoped to the authenticated user. These are minor gaps for a simple list tool, but they prevent a 5.

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 entirely. It does so clearly: domain_id is explained as 'Optional domain ID to filter VLANs' and limit as 'Maximum number of VLANs to return (default: 20, max: 1000)'. This adds meaningful semantics beyond the bare integer/string types in the schema, fully disambiguating both parameters.

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 a specific verb and resource: 'List VLANs from phpIPAM.' This distinguishes it from sibling tools like list_sections, list_nameservers, list_vrfs, etc., because it names the exact entity being listed. There is no ambiguity about what the tool does.

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 no guidance on when to use this tool versus alternatives. It does not mention any conditions, exclusions, or refer to sibling tools such as search_subnets or get_subnet_details. The only usage hint is the purpose itself, which is not enough to route an agent to the right tool when multiple list/search tools exist.

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 must disclose behavioral traits. It does mention the default limit of 20 results and a maximum of 1000, which is a concrete behavioral aspect. However, it does not state that this is a read-only operation, nor does it explain pagination or what happens when more than 1000 VRFs exist. The information is partial but not misleading.

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 core purpose, and includes a structured 'Args' section. It uses minimal words while conveying essential details about the limit parameter. No filler or redundant information is present.

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 list tool with one optional parameter, the description covers the core usage. Since an output schema exists, return format is likely handled there. The only minor gap is that it does not mention whether pagination is needed for more than 1000 VRFs, but this is a rare edge case and not critical for typical 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?

Schema description coverage is 0%, so the description must compensate. It fully explains the 'limit' parameter: its purpose (maximum number of VRFs), default value (20), and maximum allowed (1000). This is clear and adds meaning beyond the schema, which only provides type and default.

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 verb 'List' and the resource 'VRF instances' from phpIPAM, which is specific and unambiguous. However, it does not explicitly distinguish itself from sibling tools like list_vlans or list_sections, though the resource type makes the distinction implicit.

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 no guidance on when to use this tool versus alternatives. It simply states its purpose and parameter, with no mention of exclusions, conditions, or alternative tools. The only hint is the tool name itself, but no explicit routing is offered.

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 does disclose a useful behavioral trait: the IP parameter is optional and the tool will find the first available IP. However, it omits permission requirements, conflict handling, idempotency, and effects of existing reservations, leaving significant gaps.

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: a clear one-sentence purpose followed by a structured Args list. Every sentence and field earns its place, with 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?

An output schema exists, so return values need not be explained. All parameters are covered, and the optional behavior of ip is described. However, the description lacks explicit usage context such as when to prefer this over update_ip_address and what happens on conflicts, making it mostly complete but not exhaustive.

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 0% description coverage, so the description's Args list fully compensates by explaining each parameter (subnet_id, ip, hostname, description, owner). It also adds the optional auto-selection behavior for ip, providing meaning far beyond the bare schema fields.

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 begins with 'Reserve an IP address in a subnet', a specific verb plus resource that clearly identifies the operation. This distinguishes it from sibling tools like search_addresses, update_ip_address, and delete_ip_address.

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 does not explicitly state when to use this tool versus alternatives such as update_ip_address, nor does it mention prerequisites or exclusions. The usage is implied by the action word 'Reserve', providing only indirect 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 burden of behavioral disclosure. It does reveal a key behavioral trait: results are limited to 10 by defaultage, and the 'limit' arg adds a max of 1000. However, it does not mention whether searches are partial or exact, or any other operational behavior beyond the default limit.

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 efficient: purpose first, then a brief context note, then parameter docs. The 'CONTEXT OPTIMIZATION' line is slightly redundant with the limit parameter description, but it is short and does not bloat the overall description.

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 search tool with an output schema, the description provides enough to call it correctly: purpose, parameter meanings, a default limit, and maximum limit. It lacks usage guidance vis-à-vis siblings, but that gap is already reflected in the usage guidelines 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?

Given 0% schema description coverage, the description compensates by explaining both parameters: 'ip_or_hostname' is the search termeb, and 'limit' is the maximum results with default and max values. This adds meaningful semantics beyond the bare schema titles.

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 action ('Search for') and resource ('IP addresses or hostnames in phpIPAM'), making the tool's purpose immediately understandable. It does not explicitly differentiate from the sibling 'search_hostname', but the scope is still specific enough for basic selection.

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 guidance on when to use this tool versus alternatives like 'search_hostname' or 'search_subnets'. The description implies usage simply by saying 'Search for...', but it never states appropriate contexts, exclusions, or recommendations.

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 present, so the description carries the burden. It discloses a default limit of 10 and a maximum of 50, which is helpful, but it omits other behavioral details like pagination, ordering, or exact vs partial matching semantics beyond the initial phrase. This is average 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 brief and well-structured: a clear purpose sentence, a context optimization note, and an Args list. However, the 'CONTEXT OPTIMIZATION' line overlaps with the limit argument description, creating slight 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?

Given the tool's simplicity, the presence of an output schema, and only two parameters, the description covers the essential points: purpose, arguments, and default behavior. Minor gaps like wildcard support or case sensitivity are acceptable but prevent 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?

Schema description coverage is 0%, so the description's Args section is crucial. It defines 'hostname' as the search string and 'limit' as the maximum results with default and max values, including the max 50 that is absent from the schema. This adds meaningful clarification 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's function: 'Search for IP addresses by exact or partial hostname in phpIPAM.' It uses a specific verb ('search') and resource ('IP addresses'), and the hostname focus distinguishes it from sibling tools like search_subnets or search_addresses.

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 description (when you have a hostname to look up), but there is no explicit guidance on when to choose this tool over alternatives such as search_addresses or search_subnets. No exclusions or alternative recommendations are provided.

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 are absent, so the description carries the full disclosure burden. It adds a genuine behavioral note ('CONTEXT OPTIMIZATION: Limited to 10 results by default') that explains intent beyond the schema default. However, it does not disclose match semantics (exact vs fuzzy, CIDR normalization), result ordering, or any permissions implications.

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?

Purpose is front-loaded in the first sentence and the CONTEXT OPTIMIZATION note is compact and informative. The Args block is somewhat redundant with the schema and repeats 'CIDR, description', but given 0% schema coverage the repetition is justified; little 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 documentation is covered elsewhere, and both parameters are adequately described for invocation. Missing pieces are sibling routing guidance and specificity about what 'other criteria' means — an agent can call this correctly but may pick it incorrectly.

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?

With 0% schema description coverage, the description must define parameters and does so: query accepts CIDR/description terms, and limit specifies a max of 1000 that is not encoded in the schema at all. The default of 10 is also restated, providing genuine semantic value beyond the structured 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 opens with a specific verb-resource pairing ('Search subnets') and enumerates searchable criteria (CIDR, description). However, it doesn't differentiate from siblings like search_addresses or search_hostname, and 'or other criteria' is vague about what else qualifies as a valid query.

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 guidance is given on when to prefer this tool over its search siblings (search_addresses, search_hostname) or listing alternatives (get_section_subnets). The description contains no when-to-use statement, no exclusions, and no routing hints — a real gap given 14 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 must disclose behavioral traits. It only says 'Update an existing IP address record,' revealing no information about partial vs. full update, permissions, side effects, or failure modes. The 'existing' implies a not-found error, but this is minimal.

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: a one-line purpose followed by a concise parameter list. Every sentence contributes value, though the parameter explanations are sparse.

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 an update mutation tool, the description does not clarify whether it is a partial update (only provided fields are changed) or how it behaves if address_id is not found. It also ignores the output schema, which is otherwise available. The tool is simple, but the description still leaves critical ambiguity.

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 carries the weight. It lists each parameter: address_id is explained as 'ID of the IP address to update,' while hostname, description, and owner are only given 'New ...' labels. This adds basic meaning but lacks format, constraints, or update semantics.

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 'Update an existing IP address record,' using a specific verb (update) and resource (IP address record). This clearly distinguishes it from delete_ip_address and reserve_ip_address, but it does not explicitly reference 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?

No guidance is provided about when to use this tool compared to alternatives like reserve_ip_address or update_subnet. The description lacks any context, prerequisites, or exclusions.

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 of behavioral disclosure. It states the operation but doesn't disclose side effects, whether partial updates are supported, permission requirements, or what happens to unspecified fields. The tool's mutation behavior is implied but not detailed.

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 with a single main sentence and a simple parameter list. It avoids waste, though the parameter list partially duplicates schema info. The structure is easy to skim and adequately sized.

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 mutation tool with no annotations and minimal behavioral details, this description is incomplete. It explains what and which parameters, but lacks usage context, side effects, and return behavior. Having an output schema helps but the description still feels under-specified for a 4-parameter update operation.

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 description lists each parameter with a brief explanation (e.g., 'New description (optional)') which adds meaning beyond the bare schema. However, the explanations are minimal and largely redundant with the schema's property names and default null values. It doesn't provide format, examples, or constraints.

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 'Update an existing subnet' with a specific verb and resource. It distinguishes from siblings like create_subnet and delete_subnet, though it doesn't explicitly differentiate from update_ip_address. The scope is clear enough for selecting this 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?

No guidance is provided on when to use this tool vs alternatives. It doesn't mention that this is for modifying existing subnets or what scenarios call for create/delete instead. The existence of sibling tools like create_subnet and delete_subnet is not addressed.

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