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 disclosure. It mentions the write-enable requirement and that allocation picks the first available IP, but it does not specify return values, failure modes (e.g., subnet full), persistence guarantees, or any other side effects. For a mutating tool this is a significant 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 a single, front-loaded sentence that directly states the purpose and the critical environment requirement. Every word is useful; there is no redundancy or fluff.

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 should ideally mention what the tool returns or how to interpret success, but it only covers the core action and the write-enable prerequisite. For a simple allocation tool with well-described parameters, it is minimally adequate but leaves important context (e.g., returned IP, error behavior) 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?

The input schema already provides descriptions for all 6 parameters (100% coverage), so the baseline is 3. The description adds no parameter-level detail beyond 'in a subnet', but it also does not need to since the schema already documents each parameter clearly.

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 ('Allocate'), the resource ('first available IP address in a subnet'), and the scope ('in a subnet'). It distinguishes itself from sibling tools like release (frees an address) and upsert (sets a specific address) by emphasizing automatic first-available allocation.

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 gives an important usage precondition (PHPIPAM_WRITE_ENABLED=true) and implies the tool is for automatically assigning a free IP rather than a specific one. However, it does not explicitly compare itself to alternatives like addresses.upsert or addresses.release, nor does it state when not to use 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?

No annotations are provided, so the description carries full behavioral burden. It only states the action without disclosing return format, error handling, permissions, or side effects, 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 a single, front-loaded sentence with no extraneous words. It is highly concise and efficient.

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 get operation with full schema coverage, the description is minimally adequate. However, it omits details like output format or behavior when both id and ip are provided, leaving some completeness gaps.

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

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

Schema description coverage is 100%, with id and ip both described. The description adds no extra semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves a specific address by either ID or IP, which is a specific verb+resource combination. It distinguishes from sibling tools like list (multiple addresses) and search (query-based).

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 use when a specific address is needed by ID or IP, offering clear context. However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of the most explicit guidance.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It only restates the tool's purpose without adding details like pagination, ordering, permissions, or response format. The term 'list' implies a read operation, but no additional context is given.

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 single sentence is direct, front-loaded with the action, and contains no filler. It is appropriately sized for a simple list operation.

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

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

The tool is simple with one parameter, and the schema covers that parameter. However, with no output schema and no mention of response format or limitations (e.g., pagination for large subnets), the description is minimally adequate but leaves some context gaps.

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

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

Schema description coverage is 100% ('Subnet ID'), and the description reinforces the meaning of subnetId by stating addresses are in a subnet. This adds minimal value beyond the schema, so a baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') and resource ('all addresses in a subnet'), clearly distinguishing this from siblings like addresses.get (single address) or search. It precisely states the action and scope.

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: use this tool to list addresses belonging to a specific subnet. However, there is no explicit guidance on when to choose this over alternatives (e.g., search or addresses.get) or any 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?

With no annotations provided, the description carries full burden. It discloses the write-enabled requirement but omits critical behavioral traits such as whether deletion is permanent, what response is returned, whether the operation is idempotent, and what happens if both id and ip are provided. The destructive nature is implied but not elaborated.

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 concise sentence that front-loads the purpose and follows with the key prerequisite. Every word earns its place with 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?

Despite having only two parameters and no output schema, the description omits essential context such as return values, error behavior, reversibility, and how to choose between id and ip. The prerequisite is useful but not sufficient for a mutation 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?

The schema already provides 100% coverage with descriptions for both parameters. The tool description adds no extra meaning beyond the schema, so it meets the baseline but does not exceed it.

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 ('Release (delete) an IP address') with a specific verb and resource, distinguishing it from siblings like allocate and upsert which create/update addresses. The parenthetical 'delete' removes any ambiguity about the operation.

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 mentions a prerequisite ('Requires PHPIPAM_WRITE_ENABLED=true') but provides no guidance on when to use this tool versus alternatives. It does not state behavioral rules, exclusions, or preferred scenarios, leaving the agent to infer usage solely from the name.

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 full burden. It states the write nature and an environment variable requirement, but lacks detail on idempotency, field overwrite behavior, response format, or side effects. For a mutation tool this is a significant 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?

Two sentences, front-loaded with purpose and then a requirement. Zero waste.

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

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

Despite high schema coverage, the tool has 7 params, no output schema, and no annotations. The description does not explain expected behavior on conflict, prerequisites like existing subnet, or what the response contains. Incomplete for a mutation 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 100%, so schema already documents all params. The description adds no extra param semantics beyond implying that IP and subnetId are key identifiers.

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+resource ('Create or update an IP address') and clearly indicates the upsert semantics. It distinguishes from siblings like list/get (read-only) and allocate/release (different operations).

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 on when to use this vs alternatives. The requirement flag PHPIPAM_WRITE_ENABLED=true is a prerequisite, not a selection guideline. No mention of when to prefer this over addresses.allocate or subnets.ensure.

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 bears the burden. It accurately describes a read-only health check but does not disclose response format, error behavior, or whether any data is modified. No contradiction, but minimal 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 one short sentence that communicates the tool's purpose without unnecessary words. It earns its place and nothing more.

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-parameter health check, the description is mostly complete. It lacks explicit details about the return value or status output, but this is a minor gap given the tool's simplicity.

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 are zero parameters and schema coverage is 100%, so no parameter description is needed. The description fully aligns with the empty 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 states a specific verb ('check') and resource ('phpIPAM') with a clear scope ('connectivity and authentication status'). This clearly distinguishes it from sibling tools that list, get, ensure, allocate, release, or search.

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 indicates a diagnostic purpose but does not explicitly say when to use this tool (e.g., before other phpIPAM operations) or mention alternatives. It implies usage as a health check but lacks explicit 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention result format, case sensitivity, wildcard support, error handling, or whether this is a read-only operation. The description only states the action without revealing expected behavior beyond the obvious search intent.

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, focused sentence with no wasted words. It front-loads the core purpose immediately, naming both the action and the target resource without any redundant phrasing.

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

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

The tool is simple with only two fully described parameters, and no output schema exists. The description does not explain what a successful search returns (e.g., a list of matching addresses) or any limitations, but the minimal complexity and parameter richness partly compensate. It is borderline adequate but leaves the agent with unknowns about the response structure.

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 covers both parameters with 100% description coverage, providing the baseline of 3. The tool description adds little beyond the schema, only restating that search can be by IP, hostname, or other criteria, which is already captured in the query parameter description. No extra semantic depth is added.

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 ('Search') and resource ('addresses'), and lists criteria (IP, hostname, other) that distinguish it from sibling list/get functions. It is a precise statement of 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 gives context that the tool searches by various criteria but does not explicitly compare to alternatives like addresses.list or addresses.get. The usage is implied by the word 'search', but no direct guidance is provided on when to prefer this over sibling 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 provided, so the description carries full burden. It discloses required environment variables and the core behavior ('create if missing'), but does not clarify behavior when the section already exists (e.g., idempotent no-op), error handling if prerequisites are unmet, or return value. This is partial transparency for a mutation tool.

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

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

The description is a single concise sentence that front-loads the main action ('Ensure a section exists') and adds a critical prerequisite. No wasted words; every element contributes to understanding the tool's purpose and usage conditions.

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

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

The tool is simple (3 params, no output schema), but the description omits details like idempotent behavior, response format, or interaction with parent sections. Given the lack of annotations and output schema, a bit more context (e.g., 'returns section ID' or 'no-op if exists') would improve completeness.

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%, with each parameter having a basic description ('Section name', 'Section description', 'Parent section ID'). The tool description adds no extra parameter nuance, so baseline 3 is appropriate. The schema carries the parameter meaning sufficiently.

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 and resource: 'Ensure a section exists (create if missing).' This clearly indicates the tool's function and distinguishes it from list/get tools, though it does not explicitly mention sibling tools as alternatives. The wording is unambiguous and focuses on creation/verification.

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 when a section needs to be created if absent, but it does not explicitly state when to use this tool over alternatives like list or get. It provides a prerequisite condition (environment variables) that serves as guidance, but lacks explicit 'when not to use' or alternative 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 provided, so the description carries the full burden of behavioral disclosure. The description only states the basic action and does not mention what happens if neither id nor name is supplied, if both are provided (precedence), or if no matching section is found. These are important behavioral traits for a get operation that the description leaves unaddressed.

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 conveys the core purpose without redundancy or extraneous detail. Every word serves a purpose, making it optimally concise for an agent to parse.

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

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

Despite the tool's simplicity, the description is incomplete for successful invocation. Both parameters are optional in the schema, but the description does not state that at least one of id or name should be provided, nor does it explain the behavior when both are absent. Additionally, there is no output schema, and the description does not indicate what the tool returns (e.g., section object, null, error). These gaps limit the agent's ability to use the tool reliably.

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

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

The input schema already provides complete descriptions for both parameters, including the fact that name is an alternative to ID. The description adds little beyond restating 'by ID or name', and it doesn't clarify parameter precedence or formatting. With 100% schema coverage, the baseline is 3, and the description does not meaningfully elevate above that baseline.

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 'Get a specific section by ID or name' uses a specific verb (Get) and resource (section), and clearly distinguishes itself from sibling tools like sections.list (which lists all sections) and sections.ensure (which creates/updates). The scope is narrowed to retrieval by ID or name, making the tool's purpose unmistakable.

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

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

The description implies this tool is for retrieving a single section when the caller knows its ID or name, but it does not explicitly state when to use it over alternatives like sections.list or sections.ensure. There are no mentions of exclusions, prerequisites, or comparisons to sibling tools, leaving usage guidance implicit rather than explicit.

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 transparency. 'List all sections' clearly indicates a read-only action, which is transparent enough for a simple no-parameter operation. However, it does not disclose potential behaviors like pagination, empty results, or error conditions, which could be relevant in some scenarios.

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 sentence that is concise and front-loaded with the essential information. Every word contributes to the meaning, and there is no wasted text 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's simplicity (no parameters, no output schema, and a straightforward list operation), the description 'List all sections in phpIPAM' provides all necessary context. It clearly states the resource and scope, making it fully self-contained for an agent to select and invoke the tool correctly.

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

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

The input schema has zero parameters, so there is no parameter ambiguity. The baseline for zero-parameter tools is 4, and the description adds no conflicting or extraneous information. It simply states the action, which is sufficient.

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 'List all sections in phpIPAM' uses a specific verb ('list') and resource ('sections'), clearly indicating the tool's function. It distinguishes from sibling tools such as 'sections.get' (which likely fetches a single section) and 'sections.ensure' (which creates/updates), making the purpose 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?

No explicit guidance is provided on when to use this tool versus alternatives. The description only states the action, and while the name 'list' implies a broad listing operation, it does not mention exclusions (e.g., 'use sections.get for a specific section') or provide any comparison to sibling 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?

With no annotations, the description carries full burden. It states this is a write operation and lists required flags, but fails to disclose idempotency, behavior when subnet already exists, return values, or error conditions. Minimal behavioral disclosure.

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 concise clauses: purpose first, then requirement. No wasted words, well-structured and front-loaded.

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

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

For an ensure/write tool with no annotations and no output schema, a one-sentence description is insufficient. It lacks behavior on existing states, return format, and error handling, though prerequisites are included.

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

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

The input schema has 100% coverage with descriptions for all 5 parameters, so the schema already provides parameter meaning. The description adds no parameter-specific details, making 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 'ensure' with resource 'subnet' and clarifies 'create if missing', making the core purpose clear. It distinguishes from read-only tools like list/get, though it doesn't explicitly differentiate from sections.ensure.

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 prerequisites (environment variables) but offers no guidance on when to use this tool versus alternatives. It does not mention checking existence with get or the relationship with similar ensure 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 provided, so the description must carry the full burden of behavioral disclosure. It only states the action without explaining precedence when both 'id' and 'cidr' are given, behavior when neither is provided, or failure modes. It also does not explicitly confirm this is a read-only operation or describe the return format, which is critical given no output schema.

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

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

The description is a single, focused sentence that front-loads the verb and resource. No unnecessary words or redundancy. It efficiently conveys the tool's purpose and key parameter distinction.

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

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

The tool is relatively simple, but the description leaves important gaps: it does not indicate that one of 'id' or 'cidr' is required (schema lists them as optional), nor does it describe the return value. With no output schema and no annotations, these omissions make the description less complete for an agent needing 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 input schema already provides 100% coverage of parameter descriptions, but the description adds meaningful semantic value by stating 'by ID or CIDR notation', clarifying that 'id' and 'cidr' are alternative identifiers rather than both being required. This simple additional context helps the agent understand the intended parameter relationship beyond the schema.

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

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

The description 'Get a specific subnet by ID or CIDR notation' clearly states the verb ('Get'), the resource ('subnet'), and the scope ('specific'), which distinguishes it from sibling tools like 'subnets.list' that return multiple subnets. The purpose is unambiguous and immediately actionable.

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 for retrieving a single subnet, contrasted with listing multiple, but it does not explicitly name alternatives or provide exclusions. It also does not state that exactly one of 'id' or 'cidr' should be provided, leaving the parameter selection partially ambiguous. The sibling tool names offer context, but the description itself lacks direct guidance.

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

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It states the basic action but does not describe return format, pagination, ordering, whether child subnets are included, or any permissions or side effects. This is minimal 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 a single, concise sentence that immediately states the tool's purpose. It is front-loaded and contains 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?

The tool is simple, with one parameter and no output schema. The description adequately conveys the primary purpose but lacks details on return structure or behavior. Given the lack of annotations and output schema, the description is minimally viable but leaves room for interpretation about the exact output.

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

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

The input schema already provides the parameter 'sectionId' with a simple description 'Section ID'. The tool description adds context by clarifying that the section is the scope for listing subnets, but it does not elaborate on the expected value format or any special cases. Given the 100% schema coverage, this is sufficient but not enhanced.

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 'List' with a resource 'subnets' and a clear scope 'in a section'. It distinguishes from sibling tools like subnets.get (which retrieves a specific subnet) and sections.list (which lists sections).

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: to list all subnets within a particular section. However, it does not explicitly state when to use it over alternatives, nor does it mention any limitations or exclusions. There is no direct comparison to sibling tools like subnets.get or addresses.list.

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