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

With no annotations, the description carries the full behavioral burden. It does disclose the meaningful outcome (device reconnects and receives configuration), but omits whether the call is idempotent on an already-active device, what permissions are required, and what the response contains.

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

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

Two tightly written sentences with the action and its effect front-loaded, followed by the HTTP endpoint for API context. No filler, though the raw URL adds little for an agent that already knows the tool.

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 state-toggle tool with no output schema and no annotations, the description covers what the agent needs: which device, and what activation does. Return format and error conditions are the only notable omissions, and they are minor here.

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% for the single 'id' parameter, so the schema already explains that it accepts a UUID or ID. The description adds no syntax or format detail beyond that, which is the expected baseline when the schema does the work.

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 ('Activate') and resource ('device') plus the resulting behavior ('reconnect and receive configuration'), which clearly separates it from openwisp_deactivate_device in the sibling list. It stops short of explicitly naming the inverse tool, but the 'deactivated device' framing makes the distinction inferable.

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

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

Usage is implied rather than stated: the tool applies to a device currently in the deactivated state, and the sibling openwisp_deactivate_device is the obvious counterpart. There is no explicit when-to-use/when-not-to-use guidance or named alternative, so this is minimum-viable.

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 only the HTTP method and endpoint; it says nothing about required permissions, whether imported certs are validated, what the server generates when certificate/private_key are absent, or anything about the response.

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 compact fragments: a category tag for routing plus one action sentence. Nothing is wasted, and the action precedes the endpoint detail. The category prefix is boilerplate but aids discovery.

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 no output schema, the definition is minimally viable: the purpose is clear and all parameters are schema-documented. It stops short of explaining the conditional create/import behavior and any mutation side effects, which an agent would need before calling it confidently.

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

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

Schema coverage is 100%, so the schema already documents name, certificate, and private_key. The description hints at the create-vs-import distinction that maps onto the two optional parameters, but adds no format or conditional details beyond the schema, matching the baseline 3 for fully covered 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 description gives a specific verb+resource: 'Create or import a certificate authority', and the endpoint note (HTTP POST /api/v1/controller/ca/) confirms the target resource. It is clearly distinct from openwisp_create_cert, openwisp_update_ca, and openwisp_get_ca, though it does not explicitly name any sibling to differentiate.

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?

'Create or import' implies two modes but never states the condition that selects one (e.g. supplying certificate+private_key triggers import, omitting them triggers generation). There is no when-to-use guidance and no reference to alternatives such as openwisp_update_ca or openwisp_create_cert.

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 implies a write/import operation but says nothing about authorization requirements, whether an imported certificate needs both certificate and private_key, or what happens on duplicate names.

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?

Extremely short and front-loaded: category tag, then the action, then the endpoint. No wasted words, though the brevity contributes to the behavioral gaps noted elsewhere.

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, no output schema, and no return-value description, the definition leaves too much unspecified — especially the create-vs-import fork, which is the single most important thing an agent must get right here.

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 each of the four parameters is already documented with its meaning. The description's phrase 'create or import' hints that certificate/private_key are for the import path, but adds no format or pairing rules beyond the schema.

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

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

States a specific verb pair (create or import) plus the resource (certificate), and the category tag plus HTTP endpoint confirm the domain. It doesn't explicitly name how it differs from siblings like openwisp_update_cert or openwisp_renew_cert, but the create-vs-mutate distinction is reasonably clear.

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

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

No guidance on when to create a fresh certificate versus importing an existing one, nor any mention of prerequisites such as needing a CA. The agent has to infer usage from the name alone.

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 disclosure burden, yet it only supplies the HTTP method and endpoint. It does not state permission/auth requirements, whether the credential is bound to a device or organization, or whether secrets are write-only or retrievable.

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?

Very short and front-loaded, with the verb+resource leading and the endpoint detail trailing. Efficient overall, though the category prefix and raw HTTP path are marginally redundant for an agent.

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

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

For a create tool with no annotations and no output schema, the description is thin: it never says what is returned, what scope the credential belongs to, or what errors/permissions apply. The fully documented 3-param schema keeps it at merely adequate rather than inadequate.

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% – name is required, and username/password are documented in the schema – so the schema does the heavy lifting. The description adds no parameter meaning beyond restating the resource, making the baseline 3 appropriate.

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

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

States a specific verb+resource: 'Create a connection credential', which is unambiguous and distinguishable from sibling operations like update_credential or list_credentials. It lacks explicit contrast with siblings, but the verb-resource pairing is clear.

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

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

No indication of when to use this tool versus alternatives, nor any prerequisites or context for creating a credential. The bracketed category tag is a taxonomy label, not usage guidance.

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

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

No annotations provided, so the description carries the full behavioral burden. It states the operation is a POST (mutating), but does not mention auth requirements, idempotency (MAC uniqueness), what happens on duplicate MAC, or success/return semantics. For a creation tool with zero annotation coverage, this is a notable 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 compact sentences: a category tag, a specific action, and the HTTP endpoint. No filler, front-loaded action verb. Every clause earns its place.

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

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

A mutation tool with no annotations, no output schema, and no behavioral detail. It does not explain return values, prerequisite resources (e.g., organization must exist), or authorization. For a 5-parameter device-creation tool, the description is too thin.

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 baseline is 3. The description adds no parameter-level meaning beyond the schema, but all five parameters already have clear descriptions (examples for mac, name, model; default for system).

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

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

Specific verb+resource: 'Register a new network device in OpenWISP Controller.' Distinguishes from siblings like update_device, delete_device, list_devices by the 'create' verb, and the HTTP POST line reinforces creation. Lacks explicit sibling differentiation, which caps it below 5.

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

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

No when-to-use guidance, no prerequisites (e.g., requires org exists, requires token), no statement of when to use this vs. openwisp_activate_device or openwisp_create_device_connection. The category tag and endpoint are the only 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?

No annotations are provided, so the description carries the full behavioral burden. It implies a mutating POST and discloses the endpoint, but says nothing about required permissions, whether the device must already be registered, idempotency/duplicate handling, or what the response contains.

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

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

A single tight sentence with the action front-loaded, followed by the endpoint parenthetical. Nothing is wasted, though the endpoint boilerplate is low-value padding.

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 creation tool with no annotations, no output schema, and no explanation of what a device 'connection' represents or what happens on success, the description is too thin. The schema covers the inputs adequately, but the behavioral side is left entirely unaddressed.

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', 'name', and 'credential' each documented in the schema, so the schema does the heavy lifting. The description adds no meaning beyond the schema (e.g. that 'credential' is optional or what formats are accepted), which is the baseline expectation here.

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

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

States a specific verb ('Create') and resource ('connection for a device'), and the naming plus the category tag readily distinguish it from openwisp_list_device_connections, openwisp_get_device_connection, and the update/patch/delete siblings. It stops short of explicitly routing the agent versus those siblings, 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?

There is no guidance on when to create a connection versus updating an existing one, no prerequisites (e.g. device must be registered, credential must exist), and no mention of alternatives. The endpoint path is the only operational 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?

No annotations are provided, so the description carries the full burden. It notes the POST endpoint but says nothing about required permissions, organization scoping behavior, whether duplicate names are rejected, or what happens on success. For an unannotated 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?

One compact sentence plus a category tag and endpoint, front-loading the core action. No filler, though the bracket category tag is marginally useful metadata rather than substance.

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 fully documented schema lets an agent construct the call, and no output schema means return values needn't be explained. However, for an unannotated write tool with org-scoping parameters, the absence of any behavioral or usage context leaves real 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 all three parameters (name, organization, organization_slug) documented inline. The description adds no semantics beyond that, so the baseline of 3 applies.

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

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

States a specific verb ('Create') and resource ('device group'), and the HTTP endpoint reinforces the operation. The sibling set contains create/list/get/update/delete variants, and the name plus verb identifies this one as the creation tool without opening the schema.

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

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

No guidance on when to use this versus alternatives such as openwisp_update_device_group or openwisp_create_device regarding organization scoping. The only implicit signal is the verb in the name; there are no prerequisites or conditions stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses the HTTP verb/path (PUT), which implies idempotent overwrite semantics, but says nothing about required permissions, what happens if the device already has a location, or whether the assignment is reversible.

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, front-loaded sentences with no filler. The bracketed category prefix is mild overhead but the operational statement leads.

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 two-parameter assignment tool with a complete schema and no output schema, the description is just barely adequate. It omits the effect on any pre-existing location assignment and the response shape, which an agent would need to reason about the outcome.

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% ('Device UUID or ID', 'Location UUID or ID'), so the schema already documents both parameters. The description adds no format, ordering, or constraint detail beyond that, which is the expected 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?

States a specific verb and resource: 'Assign a location object to a device,' plus the concrete endpoint. It is clear what the tool does, though it does not distinguish itself from the closely named sibling openwisp_update_device_location, 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?

No guidance on when to use this versus openwisp_update_device_location or openwisp_get_device_location, and no prerequisites (e.g. the device and location must already exist). The category tag is the only organizational cue.

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 says 'Create' and gives an HTTP POST, implying a write, but does not disclose permissions, side effects, idempotency, or whether the floor plan is scoped to an organization. For a mutation with zero annotation coverage, this is a notable 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?

One short sentence plus a bracketed category and HTTP path. It is front-loaded and contains no filler, though the endpoint path is arguably redundant given 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 creation tool with no annotations, no output schema, and no guidance on prerequisites or fields, the description is minimal. An agent cannot determine required org context or what a successful creation returns, so completeness is inadequate.

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

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

Schema description coverage is 100%, so both parameters (name and organization) are fully documented in the schema. The description adds no parameter semantics beyond what the schema already provides; baseline 3 applies.

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

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

States a specific verb+resource ('Create a floor plan'), which is clear and distinguishable from siblings like openwisp_update_floorplan or openwisp_get_floorplan. However, it offers no differentiation beyond the name itself, leaving the agent to infer the distinction.

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

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

No when-to-use guidance is provided. The description does not clarify prerequisites (e.g., an organization must exist) or when to choose this over other creation tools. The HTTP endpoint is included but that is not usage guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the HTTP method (POST) and endpoint, which is useful, but doesn't say what happens on success, whether the operation requires specific permissions, if it's idempotent, what errors may occur (e.g., name conflicts), or whether creating a location has side effects. For a mutation tool with zero annotation coverage, 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?

The description is a single sentence with a category tag and endpoint, front-loaded with the core action. It is efficient and contains no waste, though the category tag adds little value for an agent that already knows 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?

Given that this is a mutation tool with no annotations, no output schema, and a complex sibling landscape, the description is incomplete. It doesn't explain return values (success response, created ID), permissions needed, or how it relates to other location creation and management tools. It meets the bare minimum of stating what the tool does but leaves the agent without enough context to call it confidently in ambiguous situations.

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 the schema already documents both parameters with clear descriptions. The description adds no parameter-level information beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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: 'Create a controller location.' This is clear and distinct from siblings like openwisp_get_location, openwisp_update_location, and openwisp_list_locations. However, it doesn't differentiate from openwisp_create_device_location, which is a separate resource, and offers no additional context about what a controller location is relative to other location types.

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. The many location-related siblings (openwisp_create_device_location, openwisp_update_location, etc.) make explicit routing important, but the description provides none. It implies creation but doesn't state prerequisites or when this should be chosen over other location operations.

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 notes the HTTP POST endpoint but says nothing about authentication, side effects, idempotency, validation failures, or what happens on success.

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 compact sentence with a category tag and endpoint note. It is front-loaded and wastes little space, though the HTTP endpoint parenthetical is marginally redundant for an agent.

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

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

For a mutation tool with no annotations and no output schema, the description is too sparse. It does not explain permissions, return values, or error behavior, and the agent must rely almost entirely on the input schema.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters and their meanings. The description's mention of NetJSON format adds minor context but largely repeats what the schema already states for the config parameter.

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 ('Create') and resource ('configuration template') and specifies the NetJSON format. The verb distinguishes it from sibling template tools such as list, get, update, patch, and delete.

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 no when-to-use guidance, prerequisites, or alternatives. It only states what the tool does, leaving the agent to infer context from the name and siblings.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the HTTP method/endpoint and category, but says nothing about required authentication/permission level, password policy constraints, uniqueness/conflict errors, or whether the created user is immediately active or needs activation via a sibling 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?

A single compact sentence with the category tag and endpoint appended; the purpose is front-loaded with zero filler. The only inefficiency is the mention of fields the tool doesn't accept.

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 7 parameters, no annotations, and no output schema, the description does not do enough: it omits auth requirements, side effects, and what the response contains. For an unannotated mutation endpoint this is a meaningful gap.

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

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

Schema description coverage is 100%, so the baseline is 3 — each of the 7 fields is self-documented. The description adds no syntax or format guidance and instead references 'role and organization permissions' fields that do not exist in the schema, which is mildly misleading rather than additive.

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+resource ('Create a new user in OpenWISP') and tags the category and HTTP endpoint, which clearly distinguishes it from sibling read/delete user tools like openwisp_list_users and openwisp_delete_user. However, it claims the tool handles 'role and organization permissions,' which are not represented anywhere in the schema, slightly muddying exactly what this 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?

No when-to-use guidance, no prerequisites, and no routing to alternatives (e.g., when to use openwisp_create_user vs inviting an existing user). The agent must infer everything from the endpoint path.

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 yet discloses almost nothing: no auth/permission requirements, no duplicate-name handling, no idempotency or return behavior. The HTTP POST endpoint is the only oblique signal that this is a write 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 tight clauses with the action front-loaded and no filler. The category/HTTP boilerplate is marginal but harmless and non-redundant.

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

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

For a trivial one-parameter create tool with a fully documented schema and no output schema, the description is barely sufficient. It omits any auth note or post-create behavior, which matters for an unannotated 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 the sole parameter ('name': 'VPN name') is already fully documented in the schema. The description adds no format, constraint, or default information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a VPN resource') and the category tag plus HTTP POST endpoint reinforce the intent. The verb clearly separates it from list/get/update/patch/delete VPN siblings, 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?

There is no when-to-use guidance, prerequisite, or mention of alternatives. An agent can only infer from 'Create' that this is the entry point for a new VPN, with no exclusions 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 discloses the POST endpoint (a write operation) but says nothing about what deactivation actually does to the device (service impact, state change), required permissions, idempotency, or how to reverse it, which for a state-mutating tool 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?

One short sentence plus the endpoint reference; purpose is front-loaded and no sentence is wasted. The category tag and URL are extra but cheap and useful.

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

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

For a single-parameter, no-output-schema action tool, this covers what it does and when. The remaining gap is behavioral (effect on the device, permissions, reversibility), which an agent would benefit from given the absence of 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?

Schema description coverage is 100% and the single 'id' parameter is documented in the schema as a Device UUID or ID. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb (deactivate) and resource (device), and adds the operational framing 'before deletion or maintenance'. An agent can immediately distinguish it from the sibling openwisp_activate_device and other device 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?

Gives clear usage context ('before deletion or maintenance') so the agent knows the lifecycle situation in which to call it. It does not name the sibling alternative (activate_device) or state exclusions, so it falls just short of a 5.

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 for a destructive operation, yet it says nothing about irreversibility, what happens to issued certificates or VPN links, or auth requirements. Only the HTTP endpoint is disclosed.

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 short sentence, front-loaded with the action, with the category tag and endpoint as compact supporting metadata. No wasted prose, though the parenthetical adds little for the agent.

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

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

For a destructive tool with no annotations and no output schema, the description is thin: it omits side effects, reversibility, and failure/not-found behavior. It is enough to attempt the call but not enough to call it safely.

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

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

Schema coverage is 100% for the single 'id' parameter (CA UUID or ID), so the schema already documents it fully. The description adds no format or constraint details beyond the schema, which is the expected 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?

States a specific verb and resource (delete a CA) plus the underlying HTTP endpoint. This clearly separates it from siblings like get_ca, list_cas, create_ca, and update_ca, though it never names them 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?

No guidance on when to delete a CA versus revoking/updating it, and no prerequisites such as required permissions or the state a CA must be in. An agent gets the action but not the selection 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 full behavioral burden, and it only restates that this is a DELETE. It does not say whether the operation is irreversible, what happens to dependent config/VPN bindings, or whether it requires special permissions.

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 compact fragments with the action front-loaded and the category tag and endpoint kept as metadata. No wasted prose, though the brevity comes at the cost of useful detail.

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 destructive single-resource operation with no annotations and no output schema, the description is too thin: it omits irreversibility, side effects on related objects, and the delete-vs-revoke decision.

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

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

Schema coverage is 100% and the single 'id' parameter is documented as 'Certificate UUID or ID' in the schema. The description adds nothing beyond the schema, so the baseline of 3 applies.

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

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

Names a specific verb+resource ('Delete a certificate') and the underlying endpoint, so the operation is unambiguous. However, it does not distinguish itself from the sibling openwisp_revoke_cert, a meaningful PKI distinction an agent needs to make.

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

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

No when-to-use guidance and no exclusion criteria. The presence of openwisp_revoke_cert as a plausible alternative is left entirely unaddressed, so the agent has no basis for choosing between deleting and revoking.

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 confirms this is a destructive DELETE but says nothing about irreversibility, auth/permission requirements, or side effects on connections or devices that use the credential — significant omissions for a delete 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?

Front-loaded and efficient — the action and resource come first, followed by the endpoint for reference. The category prefix is boilerplate but not disruptive.

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 destructive tool with no annotations and no output schema, the description should disclose irreversibility, permission needs, and downstream effects on connections. None of that is present, leaving the agent under-informed about a destructive 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 single id parameter is fully described in the schema (100% coverage), so the schema already does the work. The description adds no format or lookup detail beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb (Delete) and resource (connection credential), plus the underlying HTTP endpoint, so the action is unambiguous. It does not explicitly contrast itself with adjacent credential tools, but the verb+resource pairing is clear enough to identify it.

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 delete a credential versus alternatives, no prerequisites, and no warning about consequences or required permissions. The agent must infer usage entirely from the name and endpoint.

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 reveals that this is a destructive DELETE operation, but does not state whether deletion is permanent, what related resources are affected, what permissions are required, or whether confirmation is needed.

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?

Extremely concise: one sentence plus the HTTP endpoint reference. The category and action are front-loaded with 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?

The tool is simple (one fully documented parameter, no output schema), so the description is adequate for invocation. However, as a destructive operation with no annotations, it should disclose irreversibility or side effects to be complete.

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

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

Schema description coverage is 100%; the single 'id' parameter is fully documented as 'Device UUID or ID to delete'. The description adds no additional meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Delete), resource (network device registration), and the system (OpenWISP Controller), with the exact HTTP endpoint. This clearly distinguishes it from sibling tools like openwisp_deactivate_device and openwisp_delete_device_connection.

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 deletion tool versus alternatives such as openwisp_deactivate_device, nor about prerequisites, permissions, or irreversible consequences. The usage context is left entirely 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?

No annotations are provided, so the description carries the full behavioral burden. It reveals the HTTP DELETE operation, but doesn't state irreversibility, permission requirements, or downstream effects (e.g., what happens to the connection record). A single sentence with an endpoint is insufficient for a destructive 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?

A single sentence with the category tag and endpoint is efficient and front-loaded. No wasted words, though the endpoint adds little beyond what the name conveys.

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 destructive operation with no annotations and no output schema, the description should disclose reversibility, auth requirements, and side effects. It only states what the tool does, leaving significant gaps for safe 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 100%, with both device_id and connection_id clearly documented as UUID or ID. The description adds no parameter meaning beyond what the schema provides, 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?

States a specific verb (Delete) and resource (a device connection) with the exact API endpoint, making scope unambiguous. An agent can distinguish it from siblings like openwisp_update_device_connection or openwisp_delete_device.

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 tool versus alternatives such as openwisp_update_device_connection or delete/update of the parent device. The name implies deletion, but no context, prerequisites, or exclusions 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?

No annotations are provided, so the description carries the behavioral burden. 'Remove the location from a device' plus the DELETE verb signals a destructive, non-reversible mutation, but it doesn't state whether removing the association deletes the location entity, what happens if no location is set, or whether it requires permissions. A note on irreversibility would meaningfully help.

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 short sentence plus the endpoint in parentheses, with no filler. The category tag adds minor clutter but the statement is front-loaded 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 DELETE of a device-location association with one fully documented parameter, the description covers the essential mechanics. Missing context includes whether the location entity is preserved, error behavior when no location is assigned, and required permissions — but the core is adequate.

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

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

Schema coverage is 100% and the single 'id' parameter is documented ('Device UUID or ID'). The HTTP path template {id} reinforces that this is the device identifier, not the location id — a subtle but useful disambiguation. No additional meaning is needed beyond the schema.

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

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

States a specific verb (delete/remove) and resource (device location), clearly distinguishing it from siblings like openwisp_get_device_location, openwisp_create_device_location, and openwisp_update_device_location. The bracketed category tag is noise but the core purpose is unambiguous.

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

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

No guidance on when to use this versus alternatives such as openwisp_delete_location (which deletes the location entity itself) or openwisp_update_device_location. An agent must infer that this removes only the association, not the location record.

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 does disclose the HTTP method (DELETE), signaling a mutating operation, but says nothing about irreversibility, permission requirements, or side effects on related resources such as locations or devices tied to the floor plan.

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 segments: a category tag, the action, and the endpoint. Front-loaded with the action and free of filler, though the category/endpoint parenthetical is more metadata than agent-facing guidance.

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

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

For a single-parameter delete with no output schema, the definition is minimally sufficient to invoke the call. However, with no annotations to cover the destructive profile, the description should have warned about irreversibility or downstream effects and does not.

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 the pk parameter is already documented as 'Floor plan UUID or ID'. The description adds only the REST path template, which confirms pk is a path identifier but adds no new semantics; baseline 3 applies.

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

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

States a specific verb+resource ('Delete a floor plan'), which is unambiguous and distinguishable from siblings like get_floorplan, update_floorplan, and list_floorplans. It does not explicitly name or contrast with siblings, but the verb alone disambiguates.

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 the verb 'Delete' – an agent can infer this is called when removal is desired, but there is no statement of when to prefer it over alternatives (e.g., update or archive), nor any precondition or caution.

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

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

No annotations are provided, so the description carries the full burden. It discloses that this is an HTTP DELETE, but says nothing about whether deletion is permanent, what related resources (devices, floorplans, location-device links) are affected, or what permissions are required.

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 compact sentence with the category tag and HTTP endpoint front-loaded. No wasted words, though the endpoint parenthetical is marginal value.

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

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

For a simple one-parameter delete with a fully documented schema and no output schema, the description is minimally adequate. However, as a destructive operation with zero annotations, it should convey consequence and permission context that is currently absent.

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% and the single pk parameter is documented as 'Location UUID or ID'. The description's {pk} template merely mirrors that, adding no new semantics; baseline 3 applies.

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

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

States a specific verb (Delete) and resource (controller location), and the HTTP endpoint reinforces scope. It distinguishes itself from openwisp_delete_device_location and openwisp_delete_floorplan by naming the resource, though it does not explicitly contrast with those 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?

No indication of when to use this versus the sibling get/update/list location tools, and no prerequisites or caveats. The agent must infer usage purely from the verb.

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 for a destructive operation and discloses nothing: not irreversibility, not required permissions, not what happens to templates still bound to devices, not the response shape. The endpoint string is the only added 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?

One short sentence, front-loaded with the action and resource, with the endpoint appended. Nothing is wasted, though the endpoint restates what the name already implies.

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 destructive tool with no annotations and no output schema, the description should at minimum flag irreversibility and any safety constraints. Those are entirely absent, leaving the agent only the bare verb.

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% — the single 'id' parameter is documented in the schema as 'Template UUID'. The description adds no syntax, format, or lookup guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a template') plus a category tag and the exact HTTP endpoint, so an agent can tell it apart from create/update/patch_template siblings. It is clear but does not explicitly name or contrast with those 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?

There is no guidance on when to use deletion versus deprecation or update, no prerequisites, and no mention that the operation is irreversible. The agent gets a verb but no condition for selecting 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 the full behavioral burden. 'Delete' implies a destructive mutation, but the description doesn't state whether deletion is permanent/irreversible, whether it cascades to related objects, or what the response looks like—significant gaps for a deletion 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?

Compact and front-loaded—the category tag, action, and endpoint are packed into two short fragments with no waste. Slightly terse, but 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 single-parameter delete tool with no output schema, the invocation essentials are covered. However, with zero annotations and no output schema, it omits the consequences of the call and the return behavior, leaving meaningful gaps for a destructive 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?

Only one parameter, and schema description coverage is 100%, so the schema already documents 'id' as 'UUID or ID of the user to remove'. The endpoint string ({id}) corroborates but adds nothing new; baseline 3 is appropriate.

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

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

States a specific verb+resource ('Delete a user account from OpenWISP') and even names the HTTP endpoint, so an agent immediately knows this removes a user. It is distinguishable from list/get/create user siblings, though it doesn't name them 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?

No guidance on when to use this vs alternatives, no prerequisites (e.g., required permissions), and no warning about confirming destructive intent. Usage must be inferred entirely from the verb.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the underlying HTTP DELETE method, which hints at a destructive, irreversible operation, but it says nothing about cascading effects on certificates, devices, or templates, permission requirements, or failure modes.

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, front-loaded fragments with no wasted words; the category tag and endpoint are compactly stated. It is arguably too terse rather than verbose, but structure is sound.

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 destructive delete with zero annotations and no output schema, the description is under-specified: it omits consequences, idempotency, permission needs, and how to obtain the ID. An agent could call it, but not confidently or safely.

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% and the single 'id' parameter is documented as 'VPN UUID or ID' in the schema itself. The description's '{id}' path notation matches the schema but adds no format or sourcing detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource ('Delete a VPN resource') and the category tag plus the HTTP DELETE endpoint make the purpose unambiguous. It is clearly distinguishable from sibling operations like openwisp_list_vpns, openwisp_create_vpn, and openwisp_update_vpn by action, though it does not explicitly name 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?

There is no guidance on when to use this versus alternatives, nor any prerequisites (required permissions, whether the VPN must be unreferenced, whether the UUID can come from openwisp_list_vpns). The agent must infer all of this from the tool name alone.

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 that the operation is an HTTP GET and returns a CRL file, which implies a read-only download, but it omits authentication requirements, response format, and any rate or size considerations.

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 a category tag and endpoint hint; there is no wasted text. It is 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 simple one-parameter download with no output schema, the description sufficiently communicates the action and the fact that a file is returned. It could mention the returned content type or confirm no transformation, but it is largely complete given the tool's narrow scope.

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%, and the single 'id' parameter is fully documented in the schema as 'CA UUID or ID'. The description adds no parameter-level meaning, so the baseline score 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?

States a specific verb and resource: 'Download a CA CRL file'. This clearly distinguishes it from sibling CA operations like get_ca, list_cas, or renew_ca, which return or modify CA metadata rather than a CRL file.

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

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

No when-to-use guidance, no prerequisites, and no alternative named. The description implies the tool is for retrieving a CRL, but an agent must infer that context on its own; nothing says when to prefer this over openwisp_get_ca or other CA 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 at all, the description carries the full behavioral burden and falls short. It implies a mutating operation via 'Execute' and the POST route, but does not state permission requirements, that a reboot is disruptive/irreversible for the target, whether the command is queued asynchronously and results retrieved later, or what the response contains.

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

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

A single front-loaded sentence with the action first, followed by the helpful category tag and endpoint. No filler, though the bracket tag and raw route are boilerplate rather than agent-facing value.

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 mutating, potentially disruptive tool with zero annotations and no output schema, the description omits the essentials: safety/permission expectations, async command delivery, and any notion of what happens to the device or how the result is fetched.

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% and the enum on 'type' documents its two values, so the schema already does the heavy lifting. The description's only added nuance is that 'custom' corresponds to a shell command, which is marginal over the field descriptions.

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 ('Execute a command on a device') and illustrates scope with concrete examples (reboot, custom shell command), plus the underlying HTTP route. It is clearly separable from sibling reads like openwisp_list_device_commands and openwisp_get_device_command, though it never names those siblings 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?

There is no when-to-use, when-not-to-use, or alternative routing guidance. The examples imply that 'custom' is for shell commands, but nothing tells the agent whether to route to this tool versus the listing/getting counterparts or when a reboot is appropriate.

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, and it does disclose the underlying HTTP GET and the /ca/{id}/ endpoint, which confirms read-only, no-side-effect semantics. However it says nothing about authentication needs, behaviour for an unknown/invalid id, or what the returned CA details contain.

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 compact one-liner with the purpose front-loaded before the endpoint annotation. Every element is short and readable, though the raw HTTP path adds little for an agent already given 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 one-parameter read there is little to explain, but with no output schema and no annotations the description leaves the shape of the returned CA details entirely unspecified. Minimum viable, not complete.

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

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

Schema coverage is 100% and the single 'id' parameter is documented there as a 'CA UUID or ID'. The description adds nothing beyond the endpoint template restating the same id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get CA details') and the category prefix places it in the Certificates & VPN domain, which distinguishes it from the many device/location/template siblings. It doesn't explicitly name the neighbouring CA tools (list_cas, update_ca, delete_ca), but the name-plus-verb is unambiguous.

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

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

No when-to-use guidance, no exclusions, no pointer to alternatives such as openwisp_list_cas for enumeration or openwisp_get_cert for certificates. The agent must infer that this is the single-CA lookup by name alone.

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 burden. It does disclose the HTTP GET method and endpoint path, which implies a safe, non-mutating lookup, but it says nothing about authentication/permission requirements, error behavior for unknown IDs, or response characteristics. This is minimal but not absent 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?

Two short fragments, front-loaded with the action and resource, with the endpoint as trailing parenthetical detail. Nothing is wasted and the key information comes first.

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

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

For a simple one-parameter read operation this is close to sufficient, but with no output schema the description should ideally hint at what "details" actually contains. As written, an agent knows how to call it but not what it will get back.

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

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

With a single parameter and 100% schema description coverage, the schema already documents "id" as a "Certificate UUID or ID". The description adds nothing beyond that, so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Get certificate details") and places it in the Certificates & VPN category, so it is distinguishable from siblings like openwisp_list_certs, openwisp_create_cert, and openwisp_revoke_cert. However, it never explicitly contrasts itself with those siblings, and "details" remains somewhat vague about what is retrieved.

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 stated when-to-use context, no prerequisite (e.g., needing an existing certificate ID), and no mention of alternatives such as openwisp_list_certs for enumeration or openwisp_get_ca for the issuing CA. The agent must infer usage entirely 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 the behavioral burden. The embedded HTTP GET and endpoint path usefully signal a read-only, non-mutating operation, but nothing is said about auth requirements, whether the credential secret is exposed in the response, or error behavior when the ID is unknown.

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 compact fragments with no filler; the action is front-loaded before the technical endpoint detail. Slightly terse but nothing 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?

For a single-parameter read tool with full schema coverage this is close to adequate, but with no output schema the description should say something about what a 'credential' returns (and whether secrets are included). Security-relevant return content is left implicit.

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

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

Schema coverage is 100% and the single 'id' parameter is documented in the schema as a 'Credential UUID or ID'. The description adds no meaning beyond that, so baseline 3 applies.

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

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

States a clear verb+resource ('Get a connection credential') and even pins the HTTP verb and endpoint path. It's distinguishable from mutation siblings like openwisp_update_credential/openwisp_delete_credential, though it doesn't clarify its relationship to openwisp_list_credentials or why 'connection' credential is named differently.

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 retrieval by ID but never states when to use this versus openwisp_list_credentials or other get_* siblings. No prerequisites or context given.

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, but the GET method and the raw endpoint path (/api/v1/controller/device/{id}/) do disclose that this is a read-only single-resource fetch. It omits any mention of auth/permission requirements, not-found behavior, or whether the response is paginated, which leaves behavioral 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 tight, front-loaded sentence preceded by a category tag and the underlying HTTP route; no filler. The parenthetical endpoint is slightly redundant with the field list but remains useful reference detail.

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 compensates by naming the primary fields returned (MAC, model, status, IP). For a simple single-id read tool, that is close to sufficient; only auth/error context 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 100%, so the single id parameter is already documented ('Device UUID or ID'). The description adds no format, uniqueness, or lookup semantics beyond what the schema states, making the baseline 3 appropriate.

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

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

The description gives a specific verb ('Get') plus resource ('device') and enumerates the returned fields (MAC address, model, status, IP address). The qualifier 'a specific device' cleanly separates it from list_devices, while the id-scoped resource distinguishes it from create/update_device.

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: 'a specific device' signals you need an existing device id, contrasting implicitly with the list endpoint. There is no explicit when-to-use/when-not guidance or named alternative tool.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the HTTP method (GET), which signals a non-mutating read, but says nothing about auth requirements, whether the command may still be pending, error handling, or what the returned details contain.

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 compact sentence plus endpoint reference, front-loaded with the category tag and the verb first. No waste, though the parenthetical endpoint is largely redundant with 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?

For a two-parameter read tool with no annotations and no output schema, the description is minimally adequate: it identifies the operation but gives no sense of what 'details' are returned (status, exit code, output payload) or any failure/permission behavior an agent might need.

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

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

Schema coverage is 100%, so both parameters are already documented as 'Device UUID or ID' and 'Command UUID or ID'. The description only mirrors parameter placement via the URL template, adding no new semantics such as accepted formats or alternate identifiers; baseline 3 applies.

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

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

States a specific verb and resource ('Get details for a previously executed device command') and the 'previously executed' qualifier distinguishes it from the sibling openwisp_execute_device_command and openwisp_list_device_commands. It stops short of naming those siblings, but the scope is unambiguous.

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

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

The phrase 'previously executed' implies the tool is for retrieving an existing command's record rather than issuing one, which is useful routing context. However, it never states when to use this versus openwisp_list_device_commands or what prerequisites (e.g., command_id must come from execute) apply.

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 bears the full behavioral burden. It discloses useful traits: the output is a generated/compiled NetJSON artifact and the underlying call is an HTTP GET (implying a safe read). It omits auth requirements, whether compilation is expensive/rate-limited, and what download actually returns.

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 action and resource. The category tag and raw HTTP endpoint are useful orientation metadata but add minor length without semantic value, keeping it just below maximum.

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 with a fully documented single parameter, the core is covered. However, with no output schema and no annotations, the description should say more about the returned NetJSON payload or any preconditions; 'compiled NetJSON configuration' is only a hint.

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

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

Only one parameter (id), and the schema documents it at 100% coverage as 'Device UUID or ID'. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (generate/download) and resource (compiled NetJSON configuration for a device), which is more precise than the sibling openwisp_get_device. It does not explicitly contrast itself with openwisp_get_template_configuration or openwisp_get_vpn_configuration, but the 'device configuration' scope is unambiguous.

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

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

There is no when-to-use guidance, no prerequisites (e.g. device must exist/be reachable), and no naming of the closely related config siblings. An agent must infer the usage purely from the tool name and resource.

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 burden. It does disclose the HTTP GET endpoint, which signals a read-only, non-mutating operation and gives a concrete target path. However, it says nothing about required permissions, 404/error behavior, or whether the returned connection includes nested data.

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 compact elements: a category tag and a purpose sentence followed by the endpoint. The purpose is front-loaded and nothing is padded, though the trailing endpoint parenthetical is mostly redundant with the description body.

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-required-param getter with full schema coverage, the description is minimally sufficient. With no annotations and no output schema, it could still say whether the connection payload is returned directly or wrapped, and what a missing connection yields, but these are modest 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% — both device_id and connection_id are documented as UUID-or-ID in the schema. The description adds no format, syntax, or lookup semantics beyond that, so the baseline of 3 applies.

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

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

States a specific verb ('Get details') and resource ('a specific device connection'), which cleanly separates it from openwisp_list_device_connections and the update/patch/delete connection siblings. It does not explicitly name those siblings, but the singular 'specific' framing makes the retrieval intent 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?

There is no guidance on when to use this versus openwisp_list_device_connections or openwisp_get_device. The only implied usage comes from the required IDs in the schema, which the agent already sees without the 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?

No annotations are provided, so the description carries the full behavioral burden. It reveals nothing about the required 'key' access credential, permissions, rate limits, or what is returned, beyond the implied read-only nature of a GET.

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 tight sentence plus the HTTP endpoint; the category tag and resource are front-loaded with no filler. It is appropriately sized for a simple read 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?

For a two-parameter read tool with no output schema, the description is minimally viable, but it leaves the unusual required 'key' credential and the 'geocoded' precondition unexplained, which an agent would need to invoke it correctly.

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

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

Schema description coverage is 100%, so both id and key are already documented structurally, which sets the baseline at 3. The description adds no further meaning about the unusual 'coordinate access key' or its relationship to the device 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?

States a specific verb and resource ('get device coordinates') plus a scope qualifier ('for a geocoded device'). It distinguishes itself reasonably from get_device_location and update_device_coordinates, though it does not explicitly name those 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?

There is no explicit when-to-use guidance or alternative routing. 'For a geocoded device' hints at a precondition but does not say what to do if the device is not geocoded, nor when to prefer this over get_device_location.

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 only the HTTP method (GET) and the path, saying nothing about authentication, permissions, error behavior, or what the returned group detail contains for a read against the controller API.

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?

Very compact and front-loaded with the category tag followed by the action and endpoint. Every element is short and purposeful, though the bracketed category prefix is metadata padding rather than task guidance.

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

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

For a simple single-parameter get there is little an agent needs, but with no output schema the description could say what the group detail includes. It is adequate but leaves a small gap on return content and the from_cert alternative.

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% and the single 'id' parameter is already documented as 'Group UUID or ID'. The description adds no format or lookup semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('details for a device group'), so the agent knows this is a single-item retrieve. However, it does nothing to differentiate itself from sibling lookups like openwisp_get_device_group_from_cert, which the agent must disambiguate on its own.

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 instruction, no mention of prerequisites, and no reference to the alternative openwisp_get_device_group_from_cert sibling. The only usage signal is the appended HTTP endpoint, which implies a GET but not the conditions that select this tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the HTTP method GET, which signals a safe read-only lookup, but it does not cover authentication requirements, not-found behavior, or org-scoping effects.

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 efficient sentence plus the endpoint, with the category front-loaded and no wasted words. It is appropriately sized for a simple lookup tool.

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 annotations and no output schema, the description should do more to describe the return value and error cases. It is minimally sufficient for invocation but leaves gaps about what the resolved device group response contains.

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 the schema already documents both the required common_name and optional org parameters. The description adds no parameter meaning beyond restating that the common name identifies the certificate.

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 ('Resolve'), resource ('device group'), and scope ('linked to a certificate common name'), with the HTTP endpoint. This distinguishes it from sibling tools like get_device_group and list_device_groups via the certificate-common-name lookup key.

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 its usage context: use it when you have a certificate common name and need the associated device group. However, it gives no explicit when-to-use guidance, no exclusions, and no routing to alternative 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 the full burden. Disclosing 'HTTP GET /api/v1/...' usefully signals a non-destructive read operation, but it says nothing about authentication requirements, the shape of the returned location object, or error behavior for a missing id.

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 compact sentence with the category prefix and endpoint, front-loading the resource being fetched. Nothing is padded, though the category tag contributes only mild organizational value.

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

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

For a simple single-parameter read with no output schema, the description is minimally adequate. It does not hint at the structure of the returned location object, which would help an agent that has no output schema to reference.

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% and the single 'id' parameter is documented as a Device UUID or ID in the schema. The description adds no extra meaning (e.g., accepted id formats) beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get a device location object') and even names the underlying endpoint, so the agent knows exactly what entity is fetched. It does not explicitly distinguish itself from close siblings like openwisp_get_location or openwisp_get_device_coordinates, so sibling differentiation is left to inference.

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 statement of when to use this tool versus openwisp_get_location, openwisp_get_device_coordinates, or openwisp_list_locations. Usage context is only implied by the name and category tag.

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. The embedded 'HTTP GET' hints at a safe read and the '{pk}/' path shows it targets one record, but nothing covers auth requirements, error behavior for missing IDs, or the shape of the returned details.

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 tight sentence with the resource front-loaded, plus a useful category tag and endpoint path. Nothing is wasted, though it is arguably too sparse for a tool with no annotations.

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 read-by-ID tool with full schema coverage, the description is minimally sufficient. However, with no annotations, no output schema, and no statement of what 'details' comprises, it leaves the agent guessing about the response.

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

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

Schema description coverage is 100% and the single 'pk' parameter is already documented as 'Floor plan UUID or ID' in the schema. The description adds no additional meaning beyond that, so the baseline of 3 applies.

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

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

The description names a specific verb ('Get') and resource ('floor plan details'), which cleanly separates it from the sibling list/create/update/delete_floorplan tools. It does not explicitly state the distinction, but the retrieval intent is unambiguous.

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

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

There is no guidance on when to use this tool versus openwisp_list_floorplans or the update/delete variants. The agent must infer that this is the single-record fetch by ID, which is reasonable but not stated.

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 only says it gets details via HTTP GET, but doesn't disclose what data is returned, any permissions required, or error behavior. For a read operation with no annotations, this is minimal 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?

Two short sentences with no waste. Front-loaded with the purpose and endpoint. Could be slightly more informative without losing conciseness.

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 tool with one parameter and no output schema, the description is adequate but not rich. It doesn't explain the return structure (which the lack of output schema requires) or any behavioral aspects. An agent can call it correctly but lacks full context.

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

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

Schema coverage is 100%, so the schema already documents the 'pk' parameter. The description doesn't add anything beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (location details), which clearly distinguishes it from siblings like openwisp_list_locations or openwisp_update_location. The HTTP endpoint adds precision, though it doesn't explicitly name siblings it differs from.

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 like openwisp_list_locations or openwisp_get_device_location. Usage context is only implied by the tool name and endpoint.

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

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

No annotations are provided, so the description carries the full burden. It discloses the HTTP GET method, which signals a read-only operation, but gives no information about authentication requirements, error behavior, or what happens with an invalid organization_pk. It adds some behavioral context but leaves clear 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 very concise and front-loads the purpose. The parenthetical HTTP endpoint is slightly redundant given the name but does confirm the method. Overall, there is no wasted language.

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-only tool with one fully documented parameter and no output schema, the description provides enough context to select and invoke it. The absence of annotations leaves some behavioral questions open, but the core purpose and parameter are clear.

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

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

There is one parameter with 100% schema description coverage: organization_pk is documented as 'Organization UUID or ID'. The description does not add any meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb and resource: 'Get organization geo settings.' It distinguishes itself from the update/patch siblings through the verb 'Get' and the HTTP GET endpoint. However, it does not explicitly name alternatives, so it falls short of the top score.

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: retrieve geo settings for a given organization. There is no explicit when-to-use guidance, no mention of alternatives like update or patch, and no conditions or prerequisites stated. This is the minimum viable level for a simple retrieval tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses the HTTP GET method, which signals a read-only operation, and says the output is 'aggregated' — useful context. However, it omits the aggregation window, permission requirements, and any rate-limit 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?

A single front-loaded sentence that states the resource and scope, followed by a compact category and endpoint tag. No wasted prose, though the bracketed category prefix and raw endpoint add little for an agent that already has 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 simple two-parameter read tool with full schema coverage, the description covers purpose and scope adequately. It does not explain the default aggregation scope when neither filter is supplied or the time window covered, which are the main remaining ambiguities 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 100%, so both filters are already documented in the schema ('User account filter', 'Organization slug or ID'). The description only restates that the query can target an organization or user, adding no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Get aggregated RADIUS bandwidth and session usage metrics', scoped to 'an organization or user'. It implicitly distinguishes itself from the sibling openwisp_list_radius_sessions by emphasizing aggregated metrics rather than session listings, though it never names that sibling 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: fetch usage metrics for an org or a user. There is no guidance on when to prefer this over openwisp_list_radius_sessions, and no explanation of what happens when both optional filters are omitted (does it aggregate across everything?).

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 behavioral burden. It does disclose that this is a read operation via the HTTP GET endpoint, but says nothing about failure modes (e.g. unknown UUID), permissions, or how large/structured the returned config may be.

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 with the category tag and endpoint suffix; the purpose is front-loaded and nothing is repeated. The raw endpoint URL is somewhat redundant with the prose but not disruptive.

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 read tool with no output schema, the description tells the agent what the resource is and what the response contains (NetJSON config structure), which is close to sufficient; only error handling and sibling disambiguation 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 coverage is 100% and the single id parameter is fully documented in the schema as the template UUID. The description only repeats the parameter as a path placeholder, adding no new semantics, so the baseline 3 applies.

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

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

Names a specific verb (Get) and resource (configuration template) and states what it returns (details including the NetJSON config structure). It does not, however, distinguish itself from the closely named sibling openwisp_get_template_configuration, leaving ambiguity about which one to pick.

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: fetch a single template by its UUID. There is no statement of when to use this versus openwisp_list_templates or openwisp_get_template_configuration, and no prerequisite or context is given.

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

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

No annotations exist, so the description carries the burden. It usefully discloses that the response is a rendered tarball (a binary artifact, distinct from JSON metadata) and gives the underlying endpoint, but says nothing about auth requirements, error behavior, or whether rendering is triggered on demand.

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 compact sentences that front-load the action and artifact, with the endpoint path as a useful secondary detail. The '[Category: Templates]' prefix is mild boilerplate but not wasteful.

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 download tool with no output schema and no annotations, stating the returned artifact (tarball) and endpoint is reasonably complete. Missing only ancillary detail like auth or rendering preconditions.

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

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

Only one parameter (id) with full schema description coverage ('Template UUID'), so the schema already documents it. The description adds no format or source-of-id guidance; baseline 3 applies.

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

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

States a specific verb (Download) and resource (rendered configuration tarball for a template), which is clearly distinguishable from openwisp_get_template (metadata) and openwisp_update_template. It does not explicitly name those siblings, so 4 rather than 5.

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

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

The purpose implies when to use it (when the rendered config download is needed), but there is no explicit when-to-use, when-not-to-use, or alternative-tool guidance against the many sibling template/device 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 the full behavioral burden. It does disclose the HTTP GET method, implying a read-only operation, and enumerates returned content, but it omits permissions, error behavior for invalid IDs, and pagination details.

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 efficiently front-loaded sentence, with category and endpoint metadata compactly placed. No wasted language.

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 ID-based read with full parameter coverage and no output schema, the description does enough by enumerating the major returned sections. It stops short of covering error or edge behavior, but nothing critical is missing 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 100%, so the single id parameter is fully documented as a Topology UUID. The description adds no parameter syntax or format detail beyond what the schema already provides, making the baseline 3 appropriate.

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

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

States a specific verb+resource: retrieves network topology details including node list, link metrics, and graph connections. It clearly differs from list_topologies by being an ID-based get, but it does not explicitly name or route against 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?

No guidance on when to use this versus list_topologies, list_nodes, or list_links. Usage is only implied by the get-style name and required ID parameter.

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

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

No annotations exist, so the description carries the full burden. It does convey the non-mutating nature via 'Retrieve' and the explicit 'HTTP GET' endpoint, which signals a read-only, idempotent operation, but it says nothing about auth/permission requirements or error behavior for a missing user.

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 clauses with the category tag and endpoint in parentheses; the core purpose is front-loaded and there is no padding. Slight redundancy between 'by ID' and the endpoint's {id} placeholder.

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

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

For a single-parameter read tool with full schema coverage and no output schema, the description provides enough to invoke it correctly. It does not need to describe return values, and its only gap is the absence of any usage contrast with sibling user tools.

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% and the single 'id' parameter is fully documented as 'UUID or ID of the user'. The description's 'by ID' adds no meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb ('Retrieve') plus resource ('user') and scope ('by ID'), which clearly distinguishes it from the unbounded sibling openwisp_list_users. It stops short of naming that sibling explicitly, so the differentiation is implied rather than stated.

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

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

No when-to-use or when-not-to-use guidance is given. It never contrasts itself with openwisp_list_users or the other user siblings (create/delete), leaving the agent to infer that 'get by known ID' is the trigger condition.

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 burden. It does disclose the HTTP verb GET and the endpoint path, which usefully signals a read-only, idempotent retrieval and a single-resource lookup by ID. It says nothing about auth/permissions, error behavior for a missing ID, or response shape, so the disclosure is partial.

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 compact sentence with the category prefix and endpoint reference; it is front-loaded on the verb and resource. The endpoint fragment is arguably redundant but is short and costs nothing.

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 read with no output schema and no annotations, the description covers the minimum: what it fetches and by what key. It omits what a VPN detail object contains and how it differs from the VPN configuration sibling, which would be needed for confident routing.

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

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

Schema coverage is 100% and the single parameter 'id' is already documented as 'VPN UUID or ID'. The description adds no format, accepted-value, or lookup-semantics detail beyond the schema, so the baseline 3 applies.

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

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

States a clear verb+resource: 'Get VPN details' for a specific VPN. However, it does not distinguish itself from the nearby sibling openwisp_get_vpn_configuration, so an agent cannot tell from the description which of the two returns configuration versus VPN metadata.

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

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

No when-to-use, when-not, or alternative guidance is given. The description never mentions related tools such as openwisp_list_vpns (for discovery) or openwisp_get_vpn_configuration (for config), leaving the agent to infer 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?

No annotations are provided, so the description carries the full behavioral burden. The 'Download' verb and HTTP GET path imply a read-only, safe operation, but nothing is said about required permissions, what the returned configuration contains, or whether the download is idempotent.

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 tight sentence plus a parenthetical path reference. Front-loaded with the action, though the raw endpoint path is of marginal use to an agent.

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

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

For a single-parameter read tool with no output schema, the definition is adequate but thin: it never states what the returned configuration looks like (file format, size, encoding) which matters for a download-style 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% and the single 'id' parameter is already documented as 'VPN UUID or ID'. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Download VPN configuration'), which clearly distinguishes it from siblings like openwisp_get_vpn or openwisp_list_vpns. The category tag and HTTP path add context, but there is no explicit differentiation from other config-download tools.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named. An agent must infer that this is the tool for retrieving the rendered VPN config rather than VPN metadata.

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

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

No annotations are provided, so the description carries the full burden. It discloses the HTTP GET method and endpoint, which implies a safe, read-only operation, but omits pagination behavior, authentication requirements, and response details.

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 a category tag; every element is useful and there is no 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?

For a zero-parameter list tool with no output schema, the description identifies the resource but does not mention pagination, return format, or auth. It is adequate to start a call but leaves operational 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?

The tool takes zero parameters, so the baseline is 4; the description adds no parameter meaning and none is needed.

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 certificate authorities'), and the plural 'authorities' distinguishes it from openwisp_list_certs. It does not explicitly name the sibling or clarify the difference, so it's clear but lacks sibling routing.

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

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

No when-to-use guidance, no prerequisites, and no alternative tools mentioned. An agent must infer that this is the enumeration endpoint for CAs.

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 the HTTP method and endpoint (GET /api/v1/controller/cert/), which signals a safe, non-mutating read. It says nothing about auth requirements, pagination, or result size limits, which are the main behavioral unknowns for a list endpoint.

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 compact sentence with the category tag front-loaded and the purpose immediately readable. It is efficient, though the category prefix and endpoint restatement add little beyond the name itself.

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 read tool with no output schema and no annotations, this is barely enough: the agent knows what it lists but not what comes back, whether results are paginated, or what permissions are needed. Adequate minimum-viable coverage, not complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter meaning is degraded or contradicted.

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+resource ('List certificates') and even names the backing endpoint, so the agent knows it is a read of the certificate collection rather than a single cert. It does not, however, differentiate itself from the many sibling cert tools (openwisp_get_cert, openwisp_renew_cert, openwisp_list_cas) beyond the singular/plural distinction.

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 named alternatives; the agent must infer from the word 'List' that this is the browse/all-certificates entry point. With siblings like openwisp_get_cert and openwisp_list_cas present, an explicit routing hint would have been cheap and valuable.

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 only discloses the underlying endpoint (GET /api/v1/connection/credential/), from which read-only-ness can be inferred, but says nothing about pagination, auth requirements, or result shape for a listing endpoint.

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

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

A single front-loaded sentence with the category prefix and endpoint; no wasted text.

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-only list tool with one optional param and full schema coverage, this is close to adequate, but with no annotations and no output schema the agent gets no sense of pagination or return format, which the description could have supplied.

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% and the single optional 'search' param is fully documented in the schema, so the description adds no param detail. Baseline 3 applies when the schema does all the work.

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+resource ('List connection credentials') and is distinguishable from the sibling get_/create_/update_credential tools by the list/GET framing. The category tag and HTTP endpoint reinforce what it does, though it never names a sibling 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?

No guidance on when to use this versus get_credential, create_credential, or the broader list tools. The only implicit cue is the HTTP GET path, which an agent must infer. No exclusions or prerequisites are given.

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 behavioral load. Including the HTTP GET endpoint signals a non-mutating read, which is genuinely useful, but it says nothing about pagination, ordering, result size, or whether empty results are returned for devices with no commands.

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 plus a category tag and endpoint path, with the purpose front-loaded and no filler. Slightly denser than needed given how little it says, 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?

For a single-parameter read-only listing tool with a fully documented schema and no output schema, the description plus endpoint gives an agent everything required to invoke it correctly. The missing pagination and ordering notes are minor omissions rather than blockers.

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 a single required parameter (device_id) with 100% schema description coverage ('Device UUID or ID'), so the schema does the work. The description adds no format or constraint detail beyond the endpoint path template. Baseline 3 applies when schema coverage is complete.

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 ('List commands previously issued to a device') and includes the category tag, so the agent understands what it does. It does not explicitly differentiate from the close siblings openwisp_get_device_command or openwisp_execute_device_command, which is the only thing keeping it from a 5.

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

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

Usage is only implied: 'previously issued' suggests a historical listing versus openwisp_get_device_command for a single record and openwisp_execute_device_command for issuing a new one. The description never states when to prefer this tool or what to use instead, leaving the agent to infer the routing.

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 HTTP GET method, which implies a safe read, but says nothing about pagination, authentication, response format, or filtering 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?

Extremely concise and front-loaded: category tag, purpose, and endpoint are packed into one sentence plus a parenthetical. 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?

For a simple one-parameter list tool with no output schema and no annotations, the description is minimally sufficient for invocation but does not cover return shape, pagination, or filtering. Adequate but with clear 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% and the single id parameter is fully documented there as 'Device UUID or ID'. The description adds no syntax or format detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a clear verb (List) and resource (connections for a device), with the HTTP endpoint reinforcing the operation. It distinguishes from singular get_device_connection and write siblings by name, but does not explicitly differentiate among them in the description text.

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 tool versus siblings like get_device_connection, create_device_connection, or list_device_commands. Usage is only implied by the name and HTTP method.

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 states it's a GET (read-only implication) and gives the API endpoint, but does not disclose pagination behavior despite page/page_size params, does not mention auth requirements, rate limits, or return shape. For a listing tool with 6 params, this is a notable 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?

Extremely concise single sentence with category tag and endpoint. Front-loaded with the category and action, 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?

For a read-only list tool with full schema coverage and no output schema, the description is adequate but thin. It lacks any mention of pagination defaults, filtering semantics, or the relationship to other device group tools, which would be valuable given the six siblings for device groups.

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

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

Schema coverage is 100%, so the schema already documents all 6 parameters with descriptions. The description adds no parameter-level detail beyond restating the resource, so baseline 3 is appropriate.

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

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

Clear verb 'List' and specific resource 'device groups', with the organizational purpose stated. It does not explicitly distinguish from siblings like openwisp_get_device_group (singular retrieval) or openwisp_create_device_group, though the plural list form is inferable from naming conventions.

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

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

No when-to-use guidance beyond the obvious list semantic. The description does not mention when to prefer this over get_device_group, nor any prerequisites like authentication. It provides minimal implied 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?

No annotations provided, so the description carries the burden. It discloses the read nature through 'List' and the endpoint, but gives no information about pagination behavior, default page size, auth requirements, or limits. It also doesn't state whether results are scoped to the authenticated user's organizations.

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 plus the category tag and endpoint. Front-loaded with the primary action and resource, no wasted text.

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 list-only tool with 11 fully-documented optional filters and no output schema, the description covers purpose and identifies the endpoint. It misses when to use it versus alternatives like list_location_devices or get_device, which would strengthen the definition.

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

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

Schema description coverage is 100%, so all 11 filters are documented in the schema. The description doesn't repeat or add meaning about individual filters. Baseline 3 is appropriate – the schema does the heavy lifting.

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?

Names a specific verb (list) and resource (registered network devices) with concrete scope examples (routers, APs, switches) and points to the underlying API endpoint. Distinguishes it from sibling get_device (single fetch) and create/update/delete_device.

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?

Implied usage: listing devices within OpenWISP Controller is clear, but there's no explicit when-to-use-vs-alternatives (e.g., when to prefer get_device, or use of filters). No exclusions or routing guidance toward 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 carries the full behavioral burden, yet it only repeats the category and the HTTP verb/endpoint. It says nothing about authentication requirements, whether results are paginated or filtered by default, or what the response contains.

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

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

Extremely compact and front-loaded: a category prefix, a one-line purpose, and the endpoint. No wasted words, though the endpoint parenthetical is arguably filler for an agent.

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

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

For a simple two-parameter list tool with a fully described schema and no output schema, this is minimally adequate. It leaves open whether results are paginated or scoped to an organization by default, which matters 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 100%, so the two filter parameters (organization, organization_slug) are already fully documented in the schema. The description adds no syntax, format, or filtering nuance beyond that, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('List indoor floor plans') that an agent can distinguish from the sibling operations get_floorplan, create_floorplan, and delete_floorplan. It is clear but does not explicitly differentiate itself from other list-style siblings such as list_locations.

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 no when-to-use context, no prerequisites, and no mention of related siblings like list_location_geojson or the floorplan CRUD operations. An agent must infer usage purely 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?

With no annotations, the description carries the full burden. It discloses the HTTP GET endpoint, which usefully signals a safe read operation, but says nothing about pagination, permissions, or result ordering/count.

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 carrying category, action, scope, and endpoint with essentially no waste. The bracketed category tag is slightly noisy but harmless.

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, no-output-schema list tool this is minimally adequate, but it omits response shape hints and pagination behavior that would round out a listing endpoint.

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

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

Schema coverage is 100%, so both parameters (status, topology) are already documented in the schema. The description only echoes link-status filtering and adds no format or semantics beyond the schema 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?

States a specific verb (List) and resource (physical or virtual links between nodes) with the added scope of link status, and the endpoint confirms it. It is clearly distinguishable from topology/node siblings, though it does not name them 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?

No when-to-use guidance, no exclusions, and no alternatives named. Nothing tells the agent when to pick list_links over list_nodes or get_topology; usage is only implied by the word 'List'.

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. The HTTP GET hint implies a read operation, but there is no disclosure of pagination, result size, required permissions, or what the response contains for a listing endpoint.

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 plus a category tag and endpoint, front-loaded with the action and resource. Nothing wasted, though the URL adds little for the agent.

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

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

For a simple one-parameter list tool with no output schema, the description covers the essential call semantics but omits return-shape and pagination expectations, which matter for a listing endpoint.

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

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

Schema coverage is 100% and the single 'id' parameter is documented as 'Location UUID or ID'. The description's 'at a location' and the endpoint path merely confirm the schema; it adds no format or edge-case detail beyond it. Baseline 3 applies.

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

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

States a specific verb+resource ('List devices deployed at a location'), which is clearly distinct from openwisp_get_device_location (a device's location) and openwisp_list_devices (all devices). It does not name those siblings, but the scope is unambiguous.

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

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

No when-to-use guidance, no exclusions, no mention of alternatives such as openwisp_list_devices or openwisp_get_device_location. The agent must infer the use case from the phrase 'at a location'.

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 does not state whether the response is paginated, whether it can be large, what the GeoJSON object contains, or any permission requirement. The HTTP GET hint is a small positive but is mostly restating the read nature of the 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?

The description is a single compact sentence and is front-loaded with the category and core action. It is not bloated, though the parenthetical HTTP route is somewhat redundant for an agent that already knows this is a tool call.

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 annotations and no output schema, the description should explain the return shape (GeoJSON FeatureCollection or similar), pagination or size concerns, and sibling differentiation. It does none of these, leaving an agent uncertain how this differs from the non-GeoJSON list 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 the two filter parameters are already fully documented in the schema. The description adds no parameter-level information beyond what the schema provides, which is the baseline for high 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 states a specific verb+resource ('List locations') and names the output format (GeoJSON), which is more specific than the sibling openwisp_list_locations. However, it does not explain how it differs from openwisp_list_locations beyond 'GeoJSON format', leaving the agent to guess whether that is a render format, a file download, or a distinct dataset.

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 openwisp_list_locations, the obvious sibling. The description gives no conditions, prerequisites, or alternatives.

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

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

No annotations are provided, so the description carries the full burden. The HTTP GET hint implies a read operation, but nothing is said about pagination, ordering, empty results, or auth requirements for a location-scoped listing.

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 compact sentence front-loads the action and resource, with the endpoint in parentheses. No wasted text, though it is terse to the point of omitting context.

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 read tool with full schema coverage and no output schema, the description is minimally sufficient. It leaves out return-shape and filtering behavior that an agent could use when combining it with list_floorplans or geo tools.

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%, documenting both id (Location UUID or ID) and the floor filter. The description adds no syntax or semantic detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (indoor coordinates for a location), and the category tag plus HTTP path add useful identification. It does not explicitly distinguish itself from close siblings like list_location_geojson, so it stops short of a 5.

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

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

There is no statement of when to use this tool versus alternatives such as list_locations or list_location_geojson, nor any prerequisite or exclusion. Usage is only inferable 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 the full burden. The HTTP GET annotation implies a read operation, but nothing is said about pagination, ordering, authentication, or result size; the safety/behavior profile is essentially undocumented.

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 compact fragments with the category tag and endpoint; nothing is padded. Slight redundancy in restating the resource via both name and URL, but it stays front-loaded and readable.

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 zero-required-parameter list tool this covers the essentials of what it returns at a high level, but with no output schema and no annotations it leaves pagination, default ordering, and the distinction from other location-list siblings unaddressed.

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 search, organization, and organization_slug are already documented in the schema. The description adds no extra meaning about filter combination or semantics, which is the expected baseline when the schema does the work.

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 clear verb+resource ('List controller locations') and names the underlying endpoint, so an agent knows this is a read of location records. It does not explicitly differentiate from nearby siblings such as openwisp_list_location_devices or openwisp_list_location_geojson, but the plain 'list locations' framing is unambiguous enough.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives among the many location-related siblings (get_location, list_location_devices, list_floorplans). The agent must infer the context 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 provided, so the description carries the full behavioral burden. It adds only the HTTP GET method, which implies a read operation, but does not disclose auth requirements, pagination behavior, rate limits, or return characteristics. For a list endpoint with zero annotation coverage, 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?

The description is a single efficient sentence with the resource and category front-loaded, followed by the endpoint. The bracketed category and endpoint metadata are slightly extraneous but do not hinder readability.

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

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

For a simple one-parameter list tool, the description identifies the resource and endpoint. However, with no annotations and no output schema, it omits return structure, pagination, and any usage constraints, leaving notable gaps for an agent to invoke it confidently.

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%, and the single optional 'topology' parameter is fully documented in the schema as filtering nodes by topology ID. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb+resource: 'List nodes (routers/switches/endpoints) participating in a network topology,' which clearly identifies what the tool returns. It adds useful scope with node types and the HTTP endpoint. However, it does not explicitly distinguish itself from sibling tools such as openwisp_list_topologies or openwisp_list_links, so it falls short of a 5.

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

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

Usage is implied: an agent can infer this tool lists topology nodes, and the optional schema parameter covers filtering by topology ID. There is no explicit when-to-use guidance, no exclusions, and no alternatives named, leaving the agent to infer selection 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?

No annotations are provided, so the description carries the full burden. It discloses the HTTP method and endpoint (GET /api/v1/users/organization/), which signals a safe read operation, but says nothing about pagination, result limits, or authentication requirements.

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

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

One compact sentence with the category tag and endpoint appended; the action and resource are front-loaded with no wasted prose.

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

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

For a simple one-parameter list tool with no output schema, the core is covered, but pagination behavior and what the list actually returns remain unaddressed. Adequate but not complete.

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

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

Schema coverage is 100% with a single self-documented 'search' parameter, so the baseline is 3. The description adds no filtering syntax or matching behavior beyond what the schema already states.

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

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

States a specific verb (list) and resource (multi-tenant organizations) plus the category tag and underlying endpoint. An agent can distinguish it from other list tools by resource name, though it never explicitly contrasts with siblings like openwisp_get_organization_geo_settings.

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 versus other organization-related tools, nor any mention that the search parameter enables filtering. Usage is only implied by the word 'List'.

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

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

With no annotations, the description carries the full burden: it discloses the read-only nature indirectly via 'List' and 'HTTP GET', which is useful. However, it says nothing about pagination behavior (despite a page param), result volume, or authentication requirements, so key behavioral context is missing.

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 plus the endpoint reference, with no wasted padding. It is efficient, though the endpoint parenthetical is more structural trivia than agent-relevant content.

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