pfSense MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation4/5
Most tools have clear, distinct purposes with detailed descriptions. There is some potential confusion between similar status tools (e.g., get_openvpn_status vs get_openvpn_server_status), but the naming and descriptions generally make each tool identifiable.
Naming Consistency4/5
The vast majority of tools follow a consistent verb_noun pattern (search_*, create_*, update_*, delete_*). Minor deviations exist (e.g., bulk_block_ips, find_interfaces_by_status, manage_* tools) but they do not significantly disrupt the overall pattern.
Tool Count1/5
With 333 tools, this server far exceeds reasonable scope for an MCP tool set. Even with the broad pfSense configuration surface, such a massive number of tools will overwhelm agents and increase selection complexity.
Completeness5/5
The tool surface is remarkably comprehensive, covering nearly every pfSense subsystem with CRUD operations, settings management, diagnostics, and lifecycle actions. Obvious gaps are rare (e.g., no update for ACME settings), but overall the domain is thoroughly covered.
Average 3.7/5 across 308 of 333 tools scored. Lowest: 2.3/5.
See the Tool Scores section below for per-tool breakdowns.
- 11 of 12 community issues answered or closed in the last 6 months
- 88 commits in the last 12 weeks
- Last stable release on March 26, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, but the description adds no further behavioral context. It does not disclose that this modifies a global firewall setting, whether it affects existing connections, or whether it is reversible. The description alone provides no transparency beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but it borders on under-specification. It is concise and front-loaded but lacks substance to the point of being almost a restatement of the tool name, so it does not fully earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and complete parameter schemas, the description is too sparse for a configuration-writing tool. It does not explain the reach of the change (global vs per-interface), any prerequisite steps, or relationship to other NAT apply tools. The context signals show a complex environment with many siblings, and this description does not provide enough operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full description coverage for both parameters (mode and apply_immediately), so the description does not need to explain them. However, it also adds no additional semantic context, such as the meaning of the mode values or the effect of apply_immediately. Baseline 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (update) and the resource (outbound NAT mode), distinguishing it from the read-only sibling get_nat_outbound_mode. However, it lacks any detail about what the mode controls or what the update entails, making it minimally informative but not a pure tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, prerequisites, or alternatives. It does not mention that changes may need to be applied via apply_nat_changes, nor does it contrast with update_nat_outbound_mapping for modifying individual mappings, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. Annotations already indicate idempotent and non-destructive, but the description does not mention important details such as whether changes apply immediately (though apply_immediately is in the schema) or any effects on existing settings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at a single sentence, but it is under-specified for a tool with 9 parameters and an output schema. It lacks front-loaded detail about what specifically can be updated, making it minimally acceptable rather than well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the rich schema and output schema, the description is insufficient for understanding the full scope of the tool. It does not communicate which settings can be changed, how apply_immediately works, or any post-update considerations, leaving gaps that the schema cannot fully bridge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema fully documents all 9 parameters. The description adds no additional meaning, so the baseline of 3 is appropriate; it does not hinder or help parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update the WebGUI settings' is essentially a paraphrase of the tool name (update_webgui_settings), adding no new information. It states the action verb and resource but does not specify which settings are affected or how this differs from other update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided for when to use this tool versus alternatives. It does not mention the get_webgui_settings counterpart for reading settings, nor does it describe any prerequisites or scenarios where this update is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond the word 'Update'—it doesn't mention that changes may require a separate apply step, that settings are optional (all nullable), or that apply_immediately controls whether changes take effect right away. The description is silent on any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, and it is front-loaded. However, this brevity crosses into under-specification—it is so short that it fails to communicate the tool's purpose beyond the name. Still, from a pure conciseness standpoint, it wastes no words, so it earns a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (7 parameters, optional fields, output schema, and numerous sibling HAProxy tools), the description is critically incomplete. It doesn't explain how this tool relates to apply_haproxy_changes, which is essential for the agent to know when to call which tool. It also doesn't hint at the idempotent behavior or that partial updates are allowed. The presence of an output schema doesn't compensate for missing usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description does not add any parameter information beyond what the schema already provides. It could have summarized the settings or highlighted key behaviors like the apply_immediately flag, but that omission doesn't lower the score since the schema is self-sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update HAProxy service settings' essentially restates the tool name (update_haproxy_settings) with no additional specificity. It does not list which settings can be updated or what the outcome will be, making it nearly a tautology. A clear description would mention the specific settings (e.g., enable, maxconn, nbthread) or distinguish this from related HAProxy tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that get_haproxy_settings is for reading current settings, nor that apply_haproxy_changes may be needed to activate changes. There is no context about prerequisites or whether this tool can be used for partial updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is clear. The description adds no extra behavioral context (e.g., that changes may require a separate apply step, or that members must be valid interfaces), leaving the agent without information about side effects beyond the raw create action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal and front-loaded, but it under-specifies the tool. It is not so much concise as sparse, omitting useful context about the configuration change or how to verify success.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are presumably covered, but the description lacks information about when to use this tool, what conditions must hold (e.g., interfaces must exist), and whether apply_immediately is required. It is too bare to be considered complete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a clear description (ifname, members, descr, apply_immediately). The tool description itself adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'interface group', which is specific enough to distinguish it from sibling tools like create_interface_bridge. However, it does not elaborate on what an interface group is or when it differs from other creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives such as create_interface_bridge or apply_interface_changes. The description lacks any context about prerequisites, use cases, or when this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the inherent meaning of 'create.' Annotations only indicate non-read-only and non-destructive, but the description does not disclose side effects, application timing, or relationship to firewall rules.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence with no wasted words. However, for a tool with six parameters and alias-specific semantics, the text is under-sized and does not convey enough information to be considered appropriately structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks essential context about what a firewall alias is, how it is used in rules, and the implications of the apply_immediately parameter. Given the presence of an output schema and sibling tools, the description does not provide sufficient contextual grounding for an agent to use the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides comprehensive descriptions for all 6 parameters (100% coverage). The description references none of them directly, so it adds no additional parameter semantics beyond what the schema offers, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (create) and resource (firewall alias), making the tool's purpose evident. However, it does not explicitly differentiate from sibling alias tools like update_alias or search_aliases, so it misses 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use create_alias versus other alias-related tools. The description only states the action without any context or exclusion criteria, leaving the agent with no information about alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate readOnlyHint=false and destructiveHint=false, which match the 'Create' action, so there is no contradiction. However, the description adds no behavioral context about side effects, like whether changes require apply_haproxy_changes, impact on existing configurations, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is almost entirely redundant with the tool name. It is not verbose, yet it under-specifies; a slightly more informative summary would merit a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters and related HAProxy management tools, the description is minimal. It does not explain the role of a frontend, how it connects to backends, or when to choose this over other HAProxy tools. The output schema covers return values, but usage context is severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed parameter descriptions for bind_addresses, ssloffloadcert, and others. The description itself adds no parameter 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create an HAProxy frontend listener' clearly states the action (create) and resource (HAProxy frontend). It distinguishes from other frontend tools like update/delete/search, though it doesn't elaborate on what a frontend is or provide context for when it should be used.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as create_haproxy_backend or update_haproxy_frontend. It does not mention prerequisites, related configuration steps, or when applying changes is necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description 'Create an IPsec Phase 2 encryption entry' adds no behavioral context beyond that. It does not mention that parameters like dhgroup, prf_algorithm, and hash_algorithm are accepted for compatibility but not sent, nor that changes might need to be applied with apply_ipsec_changes to take effect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded. However, it leans toward under-specification; it essentially restates the tool name with minimal added value. For a tool with 7 parameters and behavioral nuances, this is not sufficiently informative for concise-sized, but it is still grammatically compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, ignored compatibility fields, parent_id dependency, output schema present), the one-sentence description is insufficient. It does not explain the object hierarchy (Phase 2 encryption entry belongs to a Phase 2), the fact that some parameters are accepted but not sent, or that apply_ipsec_changes may be required. The output schema may cover return values, but the description leaves important operational context unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter already has a detailed description, including notes about compatibility-only fields. The tool description adds no parameter-specific information, but per the guideline, when schema coverage is high, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'create' and identifies the resource as 'an IPsec Phase 2 encryption entry,' making the core purpose clear. It distinguishes itself from sibling tools like search_ipsec_phase2_encryptions, update_ipsec_phase2_encryption, and delete_ipsec_phase2_encryption through the verb 'Create,' and from create_ipsec_phase2 by specifying 'encryption entry' rather than the parent Phase 2 object. However, it does not explicitly highlight this distinction from create_ipsec_phase2, so it is not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It lacks context about prerequisites (like parent_id referring to a Phase 2 object), when to use this versus create_ipsec_phase2, or any exclusions. A one-line statement does not help the agent choose correctly among the many IPsec-related sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate readOnlyHint=false and destructiveHint=false, which is consistent with a create operation, but the description provides no additional behavioral context (e.g., whether changes are reversible, if it requires prior DNS resolver configuration, or how it affects DNS resolution). It simply restates the action without explaining the impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that is easy to scan. However, it is under-specified given the complexity of the tool; it is concise but not rich enough to be fully effective. It earns points for being front-loaded and brief, but could be expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and related sibling tools, the description is incomplete. It doesn't explain what DNS domain overrides are, when they should be used, or how they interact with other DNS settings. The output schema and parameter descriptions cover some details, but the tool's purpose and selection context are missing, making it insufficient for an AI agent to confidently choose this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters have descriptions in the schema (100% coverage), so the schema carries the load for parameter semantics. The description adds no extra information about parameters, such as how apply_immediately interacts with the override or what forward_tls_upstream means in this context. It stays at the baseline because schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('a DNS domain override entry'). It is distinct from update/delete/search operations, but it doesn't differentiate between DNS domain overrides and related concepts like DNS host overrides or forwarder host overrides, so it stops short of fully distinguishing among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like create_dns_host_override or create_dns_forwarder_host_override. No context, prerequisites, or exclusions are mentioned. The schema and sibling list imply ambiguity, but the description does nothing to resolve it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=false, indicating a write operation that is not destructive. The description adds no further behavioral context, such as potential impact on network connectivity, the role of apply_immediately, or reversibility. Given the annotations, the description's silence on side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence: 'Create (assign) a network interface.' It is front-loaded and includes the useful clarification of 'assign' in parentheses. No words are wasted, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a complete schema and annotations, the description is far too terse for a tool with 10 parameters and complex network implications. It fails to explain the tool's role among many interface-related siblings, the need for careful validation, or the effect of apply_immediately. The output schema helps with return values, but the high-level context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so every parameter (e.g., interface_port, typev4, ipaddr) is already documented. The description itself does not add any parameter-level meaning or relationships. This meets the baseline of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Create (assign) a network interface.' It uses a specific verb and resource, and the parenthetical 'assign' clarifies that this tool creates an interface by assigning a physical port. However, it does not explicitly differentiate itself from sibling tools like create_interface_bridge or create_interface_group, so it stops short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no context for when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or references to other tools (e.g., create_interface_bridge). This leaves the agent without guidance on choosing between related interface creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations readOnlyHint=false and destructiveHint=false, the tool is known to be a non-read, non-destructive operation, but the description adds no context about side effects, apply_immediately behavior, or reversibility. It merely restates the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but is essentially a tautology of the tool name. It does not add information, so it fails to earn its place as a description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has moderate complexity (members array, apply_immediately flag) and an output schema, but the description is too sparse. It doesn't explain what an interface bridge is, the effect of apply_immediately, or any prerequisites, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% for all parameters, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for members, descr, and apply_immediately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create an interface bridge' clearly states a specific verb and resource, distinguishing it from sibling tools like search_interface_bridges and create_interface. It unambiguously indicates the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives like create_interface_group or create_vlan, nor does it mention prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, covering the write-and-not-destructive profile. The description adds no additional behavioral context, such as whether the route is active immediately, any side effects, or whether an explicit apply step is required. There is no contradiction with annotations, but the description does not go beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It is concise and gets straight to the point. While it is under-specified, it does not waste words, earning a high score on conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 5 parameters, the presence of an output schema, and the existence of related sibling tools like apply_routing_changes, the description is incomplete. It does not mention that creating a static route may require applying routing changes to take effect, nor does it explain the typical workflow. The schema covers parameter details, but operational context is missing, making this a significant gap for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 5 parameters, including explanations for network, gateway, descr, disabled, and apply_immediately. Therefore, the schema already carries the parameter semantics. The description itself provides no additional parameter-level information, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a static route' clearly identifies the action (create) and the resource (static route). It distinguishes from sibling tools like update_static_route and delete_static_route by the action verb. However, it is a minimal restatement of the tool name and provides no additional context about the purpose or nature of static routes, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus alternatives, whether any prerequisites exist (e.g., the gateway must exist, as noted in the schema), or that changes may need to be applied via apply_routing_changes. This leaves the agent without enough context to decide between this and related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description need not restate that it is a non-read-only, non-destructive operation. However, it adds no behavioral context, such as whether changes apply immediately (despite the apply_immediately parameter) or whether a separate apply step is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with no wasted words. It earns a high score for brevity, though it may be too terse to fully support tool selection, losing one point for lack of structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with 5 parameters and an output schema, yet the description provides no contextual completeness beyond the bare action. It omits when to use, side effects, or relationship to VLAN management operations, leaving the agent to infer context from siblings and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% parameter description coverage, including descriptions for parent_interface, tag, pcp, descr, and apply_immediately. The description itself adds no parameter-level detail, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a VLAN' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'update_vlan', 'delete_vlan', and 'search_vlans'. However, it lacks additional detail such as the parent interface constraint or that it creates a VLAN on a physical interface.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to prefer create_vlan over create_interface or update_vlan. There are no prerequisites, exclusions, or context about network configuration workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: it states the tool can 'remove' an address, which is destructive, yet destructiveHint is false. The description also fails to mention the confirm safety gate required for delete operations or the apply_immediately behavior, leaving critical behavioral context undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence with no filler. It is concise, though it could have included more context without becoming verbose. Its brevity earns a high score, but it slightly misses top marks because it omits essential operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and rich parameter schema, the description lacks critical context such as the confirm requirement for delete operations, the effect of apply_immediately, and when to use this tool over similar ones. This is a non-trivial mutation tool, and the description is too minimal to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% parameter description coverage, so the description does not need to elaborate. It adds no extra meaning beyond the schema, but the baseline of 3 applies because the schema already documents each parameter's purpose and constraints clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add or remove' and clearly identifies the resource 'address for a WireGuard tunnel'. It distinguishes this from sibling tools like manage_wireguard_peer_allowed_ip by focusing on the tunnel's own address, not peer allowed IPs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as search_wireguard_tunnel_addresses for reading existing addresses or manage_wireguard_peer_allowed_ip for peer IP management. There is no mention of prerequisites, exclusions, or typical use cases beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds zero behavioral context beyond that, such as how search works, pagination behavior, or that parent_id is required. It doesn't contradict annotations, but it also provides no added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence with no fluff. It conveys the core purpose in 7 words, which is appropriately concise. It's under-specified but not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple search nature, the complete schema, and the presence of an output schema, the description is minimally sufficient but not rich. It lacks usage context and any guidance on how to find servers for a specific backend, though the required parent_id hints at this. Could be more complete with a note like 'requires backend ID' or a pointer to manage_haproxy_backend_server for modifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description doesn't mention any parameters or provide additional context beyond the schema, so it neither helps nor hinders. The schema already documents all 5 parameters clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action (search) and the resource (servers within an HAProxy backend), which clearly distinguishes it from sibling tools like search_haproxy_backends or search_haproxy_frontends. It doesn't explicitly contrast with them 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, prerequisites (e.g., needing a backend ID), or any exclusions. The description only says what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only restates the operation without adding behavioral context beyond the annotations. It does not disclose update semantics, such as partial vs. full replacement, behavior with null fields, or the effect of apply_immediately. Given annotations already cover readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description adds no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that is entirely front-loaded with the key information. It contains zero redundant or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high schema coverage and annotations, the description omits critical operational semantics for an update tool, such as how null parameters are handled, whether the update is partial or wholesale, and the implications of apply_immediately. More context is needed for correct invocation, making the description incomplete for this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all seven parameters individually described. The description itself adds no parameter-specific meaning beyond mentioning 'by ID', which reinforces alias_id but doesn't go beyond the schema's existing explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Update'), resource ('alias'), and identifier ('by ID'), which distinguishes it from create_alias and delete_alias. However, it does not explicitly differentiate from manage_alias_addresses, which could also be used to modify alias fields, so it's clear but not fully differentiated from all siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like create_alias, delete_alias, or manage_alias_addresses. There are no prerequisites, conditions, or exclusions mentioned, so the description offers no decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, idempotent, non-destructive. The description adds no behavioral context like whether unspecified values are preserved, or that apply_immediately defaults to true. It doesn't warn about requiring an existing interface or the need for a separate apply step.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence, no filler, immediately says what it does. It is front-loaded with the verb and resource, making it efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter mutation tool with output schema, the description is minimal. It lacks usage context, relationship to sibling tools, and important behavioral details like the apply_immediately parameter or that the interface must already exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so baseline is 3. The description mentions 'pool range, lease times, etc.' which are already in schema. No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update DHCP server configuration (pool range, lease times, etc.)' clearly states the verb and resource, with examples of fields. However, it doesn't explicitly distinguish from sibling tools like update_dhcp_backend or update_dhcp_address_pool, relying on the name for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It doesn't mention that changes may need to be applied via apply_dhcp_changes or that it targets an existing server identified by interface, which would help selection among many DHCP-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-readonly, idempotent, non-destructive operation, and the description adds no further behavioral context. It does not mention that only provided parameters are updated or that apply_immediately controls when changes take effect, which are critical traits beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It concisely conveys the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 optional parameters) and the existence of sibling tools like apply_dns_resolver_changes, the one-sentence description is insufficient. It omits key semantics such as partial-update behavior, the meaning of apply_immediately, and how this differs from applying pending changes. The output schema and annotations mitigate some gaps but not usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all 8 parameters, so the description does not need to elaborate. The generic 'settings' wording adds nothing beyond the schema's field-level details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' with a clear resource ('DNS Resolver (Unbound) settings'), making the action unambiguous. It distinguishes from sibling getters like get_dns_resolver_settings, but does not explicitly differentiate from apply_dns_resolver_changes, which could be confused with this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as apply_dns_resolver_changes or get_dns_resolver_settings. It lacks any context about prerequisites, partial updates, or whether changes require a separate apply step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is not read-only, is idempotent, and not destructive. The description adds no behavioral context beyond the basic operation, such as whether changes are immediate, require authentication, or could disrupt email delivery. It does not contradict annotations, but it also provides no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded and directly states the operation. However, it is so minimal that it borders on under-specification, missing valuable context that could be conveyed without verbose language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 optional parameters and an output schema, this simple description is insufficient. It does not mention that all parameters are optional, that the tool likely performs partial updates, or the significance of 'apply_immediately'. The presence of a sibling getter is not leveraged to provide context about round-tripping. An agent would need to infer critical behavior from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter has its own description, satisfying the baseline. The tool description itself does not clarify partial-update semantics, even though all parameters are optional and default to null. It does not explain that omitted parameters likely retain existing values or how 'apply_immediately' affects behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Update the email notification settings', which clearly identifies the action (update) and the target resource (email notification settings). It is distinct from the sibling 'get_email_notification_settings' because it implies a write operation. However, it lacks details about scope or context, such as system-wide vs per-user settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool or how it relates to alternatives. It does not mention that 'get_email_notification_settings' should be used to read current settings first, nor does it explain the 'apply_immediately' parameter or any prerequisites. No exclusions or alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral context beyond the verb 'update'. While annotations indicate idempotency and non-destructive nature, the description adds no value such as potential need to apply changes, possible traffic interruption, or how apply_immediately affects behavior. It merely restates what the name already conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with zero wasted words, fitting in a single short sentence. It is front-loaded and easy to parse, though it might be slightly under-specified for a tool with nine parameters, but it avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 optional parameters affecting firewall behavior), the description is severely under-specified. It doesn't explain when to use this tool, what the 'advanced settings' encompass, or the operational impact of applying changes. The output schema exists but doesn't compensate for the lack of contextual guidance about usage and effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add any additional meaning beyond what the input schema already provides for each parameter. It lists no parameter names or values in the description, relying entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update firewall advanced settings' clearly uses a specific verb ('update') and resource ('firewall advanced settings'), making the tool's purpose immediately understandable. It distinguishes itself from the sibling get_firewall_advanced_settings by implying a write operation, though it doesn't enumerate which settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool compared to alternatives, no mention of prerequisites, and no indication of how it relates to other firewall update tools. The description simply states the operation without any context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, which are consistent with an update operation. The description adds no additional behavioral context beyond the annotations, such as the effect of apply_immediately or whether changes persist without explicit apply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence expresses the action without redundancy. It is front-loaded with the verb and resource, making the purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 6 parameters and an apply_immediately flag, the description is overly terse. It does not explain the update workflow, the need to apply changes, or the relationship to search_gateway_groups. The output schema helps, but the description alone is insufficient for an agent to understand the full update process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters are fully documented in the schema with descriptions, including the trigger enum and group_id source. The tool description adds no extra parameter meaning, so the schema carries the load; thus 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('existing gateway group') with identification by ID. It distinguishes this from sibling create/delete/search operations, though it does not enumerate the specific updatable fields, which are covered in the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus create_gateway_group or update_gateway. The description does not mention prerequisites like obtaining group_id from search_gateway_groups or the apply_immediately workflow, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not state that only specified fields are updated, how apply_immediately affects runtime state, or whether changes can be reverted. Annotations indicate idempotency and non-read-only behavior, but the description adds little beyond the fact that it's an update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that directly states the operation without any unnecessary words or repetition of schema details. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (10 parameters, mutation, output schema) and the existence of apply_interface_changes and search_interface_configs siblings, the description is underequipped. It omits key context such as whether updates are partial/full replacement and how changes are applied, leaving the agent to infer critical workflow steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 10 parameters, so the description is not required to explain parameters. The description itself contributes no additional meaning beyond what the schema already provides, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('existing interface') identified by ID, which aligns with the tool's name and distinguishes it from other resource-specific update tools in the sibling list. It lacks explicit differentiation from sibling update tools, but the resource type and 'by ID' qualifier provide sufficient clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 is provided. It does not mention that interface_id can be obtained from search_interface_configs, nor does it advise on applying changes (e.g., via apply_interface_changes), which is relevant given the apply_immediately parameter and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It simply restates the tool name and does not mention potential side effects like requiring a service reload or the role of the 'apply_immediately' parameter. Annotations indicate idempotency and non-destructiveness, but the description itself is tautological.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundancy or wasted words. It is appropriately short for the simple operation, though it could have included a bit more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations, full schema coverage, and an output schema, the description is minimally sufficient. However, it lacks any usage context or behavioral notes, so it does not fully guide the agent on when and how to invoke the tool beyond the basic operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides complete descriptions for all 5 parameters (100% coverage). The description does not elaborate on any parameters, but the schema handles parameter semantics, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('NTP service settings'), clearly indicating the operation. It does not explicitly differentiate from sibling tools like get_ntp_settings or manage_ntp_time_server, but the name and description are unambiguous enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_ntp_settings or manage_ntp_time_server. There are no prerequisites, exclusions, or context about typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that this is a write operation (readOnlyHint=false), idempotent, and non-destructive. The description adds no further behavioral context, such as whether changes apply immediately by default, whether services restart, or what the output/return value looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—four words—and front-loaded with the action. Every word earns its place, and there is no wasteful or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having annotations and a well-described schema, the description lacks important contextual information for a system-level change. It does not explain the implications of changing the timezone (e.g., impact on logs, cron, or authentication), the role of the apply_immediately parameter, or any prerequisites. This is an incomplete description for an operational tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description adds no additional meaning beyond what is in the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update the system timezone' clearly identifies the action (update) and the resource (system timezone). It distinguishes from sibling tools like get_system_timezone by conveying the write nature, though it does not elaborate on scope or specifics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention the read-only counterpart or any conditions for use, leaving the agent to infer appropriateness 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, which convey safety. The description adds no additional behavioral context beyond the annotation, such as whether changes are applied immediately or require a separate apply step. This is neutral but not additive, so a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (five words), but it is also under-specified. It reads almost as a restatement of the tool name, lacking any elaboration that would help an agent. While there is no fluff, 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has five optional parameters, an output schema, and clear annotations, the description is minimally adequate. However, it fails to contextualize what 'service settings' means or how this tool fits into the WireGuard workflow. An agent would not know when to choose update_wireguard_settings over update_wireguard_tunnel or apply_wireguard_changes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the input schema already fully explains all five parameters, including types and defaults. The description merely says 'settings' without enumerating or elaborating on them, so it adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'WireGuard service settings', distinguishing it from sibling tools like get_wireguard_settings (read) and apply_wireguard_changes (apply). However, it does not specify which settings are affected beyond the generic 'service settings', so it lacks a bit of specificity compared to a higher score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it updates service-level settings rather than tunnel or peer settings, nor does it clarify the relationship to apply_wireguard_changes. An agent would have to infer usage from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive, but the description adds no additional behavioral context. It does not mention that creation may be immediate only if apply_immediately is true, nor does it explain configuration persistence or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is efficient, but it replicates the tool name and provides no structured detail. It lacks the two-sentence clarity seen in high-scoring descriptions, and the brevity borders on under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and an output schema, the description is incomplete; it offers no context about the creation effect, application behavior, or relation to peer management. The agent must rely entirely on the schema and sibling tool names to understand the operation's implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not discuss parameters, but the schema provides complete descriptions for all 7 parameters (100% coverage), so the schema carries the meaning. The tool description adds no extra semantic context beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and resource 'WireGuard tunnel', making the operation unmistakable. It distinguishes from sibling create tools like create_wireguard_peer by naming the target resource directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus create_wireguard_peer or update_wireguard_tunnel. It omits prerequisites or alternatives, leaving the agent to infer applicability 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts the annotations: destructiveHint is false, but the tool explicitly supports deleting files, and the schema confirms that delete is destructive with a confirm safety gate. This is a serious inconsistency that misleads the agent about the tool's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words, effectively conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the output schema and full parameter documentation, the description is incomplete due to the destructiveHint contradiction and lacks context on related actions like apply_haproxy_changes. The agent is left uncertain about safety and next steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds minimal semantic context by giving examples of file types, but it does not explain parameters beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create or delete), the resource (HAProxy file), and provides examples of file types, making it distinct from siblings like search_haproxy_files and create_haproxy_frontend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description simply states the action without context on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey idempotency and non-destructive behavior, but the description adds no additional behavioral context. It doesn't mention possible service interruptions, the role of apply_immediately, or any side effects of updating SSH settings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it essentially restates the tool name without adding information. It is not verbose, but it also doesn't earn its place by adding clarity beyond the identifier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters and an output schema, the description provides almost no context. It doesn't explain how parameters interact, when changes take effect, or any cautions about updating SSH settings. The description alone would leave an agent without enough information to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds no parameter-level meaning, but the schema already provides full semantics. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('SSH service settings'), which is specific and distinct from sibling tools like get_ssh_settings. It leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no prerequisites, and no mention of whether to read settings first. The description simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the operation is not read-only and not destructive, but the description adds no additional behavioral context. It doesn't disclose side effects (e.g., whether the zone becomes active immediately, what happens if the zone already exists, or whether an apply step is required).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no wasted words. It is front-loaded and easy to parse, though it could benefit from slightly more detail without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with potential side effects and an apply_immediately parameter, the description is too sparse. It doesn't explain the apply mechanism, zone types, or when to use this tool over related DNS tools. The schema and output schema help, but the description lacks critical context for an agent to fully understand the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 4 parameters, including defaults and types. The description adds no parameter information, so the baseline of 3 is appropriate for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Create') and a clear resource ('BIND DNS zone'), distinguishing it from sibling tools like update_bind_zone and delete_bind_zone. The phrase 'BIND DNS zone' adds useful context that 'bind_zone' alone doesn't provide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool, prerequisites, or alternatives. It doesn't mention relationships to other DNS management tools or when to prefer this over create_dns_host_override, for example.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive behavior, but the description adds no extra context such as whether changes apply immediately, require a separate apply step, or have any side effects. This is a notable gap given the apply_immediately parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It is appropriately brief, though it could include more meaningful context while still being concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and a clear family of sibling tools (search/update/delete), the description is too sparse. It omits important context like when to use this tool, what happens if an option already exists, and whether the change persists or needs an explicit apply. The output schema covers return values, so that absence is acceptable, but the overall context remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of parameters with helpful descriptions, so the baseline is 3. The tool description itself contributes no additional parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and resource 'DHCP custom option', which clearly distinguishes it from sibling tools like update_dhcp_custom_option, search_dhcp_custom_options, and delete_dhcp_custom_option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It only states the action and resource, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds no new behavioral information. It does not mention the effect of apply_immediately, aliases handling, or any configuration state changes, providing no value beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence 'Create a DNS host override entry' that front-loads the core action with no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and annotations provide solid structured information, the description lacks contextual nuance such as distinguishing from the DNS forwarder counterpart or explaining the apply_immediately/alias behavior. For a create tool with many siblings, this is minimally adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has full (100%) coverage with clear descriptions for all six parameters, including examples for ip and host. The description itself adds no parameter details, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Create') and resource ('DNS host override entry'), and the tool name distinguishes it from search/update/delete siblings. However, it does not explicitly differentiate from the similar create_dns_forwarder_host_override tool, so the agent must rely on the name alone to distinguish.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like create_dns_forwarder_host_override, nor any prerequisites or side-effect warnings. It simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds no additional behavioral context, such as whether changes require applying via apply_ipsec_changes or whether duplicate entries are rejected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single clear sentence with no redundant information. It is front-loaded with the verb, but offers minimal detail beyond the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description is extremely sparse. It fails to explain that parent_id must reference an existing Phase 1 entry, that some algorithms require key lengths, or that changes may need to be applied via apply_ipsec_changes. The output schema helps, but the description doesn't provide essential usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with descriptions for all 7 parameters including allowed values for dhgroup, encryption_algorithm_name, etc. The tool description adds no extra parameter information, so baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Create' and resource 'IPsec Phase 1 encryption algorithm entry', clearly distinguishing from Phase 2 encryption creation. It states exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like search_ipsec_phase1_encryptions or create_ipsec_phase2_encryption. No exclusions or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate the tool is not read-only and not destructive, but the description adds no behavioral context beyond 'create'. It does not mention whether changes need to be applied separately, whether the mapping is created active, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise, but the brevity comes at the cost of missing helpful usage and behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter create operation, the description lacks operational context: no mention of when to use it relative to other NAT tools, no relationship to apply_nat_onetoone_changes, and no explanation of the apply_immediately parameter's role. The output schema does not compensate for this missing workflow guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds no parameter-specific details, but the schema adequately documents all eight parameters, so no significant gap exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('1:1 NAT mapping'), clearly distinguishing this from sibling tools like create_nat_port_forward and create_nat_outbound_mapping. It effectively communicates the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as create_nat_port_forward or create_nat_outbound_mapping. The phrase '1:1 NAT mapping' implies a use case but does not state exclusions or reference sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=false and destructiveHint=false, so the mutation nature is already known; the description adds no behavioral context like apply semantics, service restart, or dependency on existing certificates. For a config-heavy create operation, this lack of side-effect disclosure 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. It could not be more concise, though the extreme brevity leaves little structural guidance for such a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich schema and annotations, the description is too sparse for a 25-parameter creation tool. It omits high-level guidance about mode/protocol dependencies, certificate requirements, and what 'create' implies at runtime. The output schema and parameter descriptions mitigate some gaps, but the description alone is not a complete guide to invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all 25 parameters. The description itself adds no parameter-level meaning, but because the schema carries the burden, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') paired with a concrete resource ('OpenVPN server instance') and platform ('pfSense'), making the operation unambiguous. It clearly distinguishes from sibling tools like update_openvpn_server, delete_openvpn_server, and search_openvpn_servers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool, prerequisites (e.g., CA/certificate requirements), or how it relates to alternatives such as create_openvpn_client or search_openvpn_servers. The only implied context is the verb 'Create', which is not enough for an agent to decide between similar VPN operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. However, the description adds no extra behavioral context beyond restating the filter parameter; it does not mention return behavior, data scope, or any side effects beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It communicates the core purpose efficiently, earning a high score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, output schema present, safety annotations provided), so the brief description is minimally viable. However, it lacks usage guidance to differentiate from sibling search tools, leaving a notable gap in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter, and the description offers no additional parameter-level detail. Since the schema does the heavy lifting, the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds interfaces based on their status, using a specific verb and resource. However, it does not explicitly distinguish itself from closely related sibling tools like search_interfaces, leaving some ambiguity about its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_interfaces or get_available_interfaces. No exclusions, prerequisites, or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description repeats the tool's name and adds no behavioral context beyond what the annotations already specify (readOnlyHint=true, destructiveHint=false). It does not describe any additional traits such as what data is returned or any side effects, but since annotations cover safety, the description adds little value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is front-loaded and direct. It is concise without being verbose, but it is also minimal and does not provide any additional useful detail beyond the basic function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, read-only, output schema exists), the description is minimally acceptable. However, it lacks contextual details such as what the returned settings include or how they might be used, making it slightly incomplete for a user unfamiliar with NTP.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema reflects that with an empty properties object. Per the rubric, a baseline of 4 is appropriate when there are no parameters, so the description need not explain parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the specific resource 'NTP service settings', distinguishing it from the sibling 'update_ntp_settings' tool. However, it does not explicitly differentiate itself from other get_* settings tools, though the resource name is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description simply states what it does without context about when it is appropriate or when other tools might be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotation contradiction: the description says 'remove' which is destructive, but annotations declare destructiveHint=false. This is a serious inconsistency. The description also does not disclose the safety gate (confirm must be True for delete) or the apply_immediately behavior, relying entirely on the schema for critical risk information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It directly states the core action and resource, effectively trading brevity for immediate clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the description is minimal, the schema is exceptionally rich (100% parameter coverage, output schema present, annotations available except for the contradiction). The tool is moderately complex with create/delete actions, but the schema compensates for the brief description. However, the contradiction with destructiveHint undermines overall completeness, preventing a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% per context signals, and the schema provides detailed descriptions for parameters including enum constraints, dependencies, and defaults (e.g., extaddr, confirm, extaddr_ssl). The tool description adds no parameter-level meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add or remove a bind address from an HAProxy frontend' clearly states the action (add/remove) and the resource (bind address on an HAProxy frontend). It distinguishes the tool from sibling search tools like search_haproxy_frontend_addresses and other manage tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that search_haproxy_frontend_addresses should be used for listing addresses first, nor any prerequisites or conditions for create vs. delete operations. The intended usage is only implied by the action verbs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds no additional behavioral context, such as whether settings take effect immediately or require applying changes, nor any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is immediately readable and free of fluff, achieving excellent conciseness and front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool, the schema and annotations provide most needed context. However, the description lacks mention of the apply_immediately behavior or relationship to apply_dhcp_changes, and does not emphasize that all parameters are optional. This leaves some ambiguity for an agent about the tool's effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five parameters. The description adds no extra meaning beyond what the schema provides, so score is at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and the resource (DHCP relay settings), distinguishing it from read-only siblings like get_dhcp_relay_settings. It is concise but doesn't specify which aspects are updated, though the schema enumerates them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_dhcp_relay_settings or apply_dhcp_changes. No context on prerequisites or whether changes are staged.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description adds no additional behavioral context. It does not mention side effects, the effect of apply_immediately, or runtime impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately concise, though its brevity contributes to vagueness penalized in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 optional parameters, annotations, and output schema, the description is minimal but not entirely inadequate. It lacks usage context and an overview of what console settings entail, but the schema covers parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter described (e.g., serialspeed, primaryconsole). The tool description adds no additional parameter meaning, but the schema fully documents the parameters, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and identifies the resource 'system console settings', clearly indicating the tool's action. It does not explicitly distinguish from sibling tools like get_system_console or update_system_hostname, but the update action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description lacks context about prerequisites, whether to retrieve current settings first, or how it relates to other update_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), idempotent, and non-destructive. The description adds no behavioral context beyond the obvious 'update' action—no mention of side effects, required permissions, or whether changes are applied immediately. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler or redundancy. It is front-loaded with the core action and resource, making it easy to parse at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is well-supported by a rich schema, full parameter descriptions, annotations, and an output schema. However, the description lacks any usage guidance or behavioral caveats, so it is minimally viable but not fully informative for an agent deciding when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly documented. The description itself adds no parameter-level meaning, but this is acceptable given the baseline of 3 when the schema does the heavy lifting. No extra value is provided by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('traffic limiter'), with the scope 'by ID' indicating the target. It is unambiguous and distinct from create/delete tools, but it does not explicitly differentiate itself from sibling tools or mention alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It does not mention that a limiter must already exist, nor does it point to create_traffic_limiter for new limiters or search_traffic_limiters for finding IDs. The schema hints at the source of limiter_id but the description itself lacks this context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so no contradiction exists; however, the description adds no behavioral context beyond the purpose, such as return semantics, prerequisites, or side-effect information. It does not enhance the safety profile beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately states the action and focus, which is ideal for a simple metadata lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one parameter), annotations covering read-only safety, and the presence of an output schema, the brief description is largely sufficient. It could be slightly more explicit about what 'guardrail requirements' means or that it accepts a tool name, but the schema covers the latter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter semantics are already fully documented in the input schema. The description adds no extra meaning for tool_name beyond the schema's example, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Check') and the resource ('risk classification and guardrail requirements for a tool'). It is not a tautology, but it does not explicitly distinguish this from the sibling get_guardrail_status beyond the per-tool scope implied by its name and tool_name parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool, when not to use it, or how it relates to alternatives such as get_guardrail_status. The description only states what the tool does, leaving the agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the action. While annotations indicate readOnlyHint=false and destructiveHint=false, the description does not disclose potential side effects, whether changes require explicit apply (e.g., apply_immediately parameter), or any consequences of creating a cron job.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that states the tool's purpose without filler. It is front-loaded and economical, though it provides minimal information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (8 parameters) and reliance on schema and annotations, the description alone is minimally adequate. The schema descriptions and existence of an output schema compensate for some gaps, but the description lacks usage context and behavioral nuances, making it incomplete for complex invocation scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all eight parameters, including apply_immediately, having descriptions. The description itself adds no parameter-level meaning, so it remains at the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('cron job'), clearly stating the tool's function. It distinguishes itself from sibling tools like search_cron_jobs and delete_cron_job by indicating an additive action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus other cron tools, nor does it state any prerequisites or alternatives. The agent must infer usage solely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds no behavioral information such as whether changes take effect immediately, whether apply_dns_forwarder_changes is required, or any side effects. It simply restates the action 'Create'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no superfluous words, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a clear purpose, the description lacks essential context: it doesn't explain how DNS Forwarder host overrides differ from DNS Resolver host overrides, whether an apply step is needed, or what the output shape is. It's too sparse for an agent choosing among many similar create tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all 5 parameters with descriptions (100% coverage), and the tool description adds no additional meaning or context for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the specific resource ('DNS Forwarder host override entry'), which distinguishes it from sibling tools like create_dns_host_override and create_dns_domain_override.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the similar create_dns_host_override or create_dns_domain_override tools, nor any context about prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context beyond the literal create action. It does not disclose the apply_immediately effect, config persistence, or whether the entry is active immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. It is appropriately front-loaded with the verb and object, making it instantly clear what the tool accomplishes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite full schema coverage, the description leaves out how Phase 1 relates to Phase 2 and whether creation immediately applies changes. For a complex IPsec configuration tool with 14 parameters, this minimal context is insufficient for an agent to understand the broader workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 14 parameters have descriptions in the schema (100% coverage), so the description contributes no additional parameter semantics. The schema already documents required fields, defaults, and conditions like pre_shared_key being required for pre_shared_key auth.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'IPsec Phase 1 (IKE) entry', clearly distinguishing this from Phase 2, update, and delete sibling tools. It precisely states the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this over update_ipsec_phase1, nor any prerequisites such as existing IPsec enablement or the need to create Phase 1 before Phase 2.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no behavioral details beyond the annotations, such as whether changes take effect immediately, whether the tool creates a pending configuration, or whether an apply step is required. Given that this is a creation tool with no annotation coverage of such side effects, the description should have provided more context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, directly front-loaded with the action and resource. It contains no extraneous words and is highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the schema and annotations are rich, the description is too terse for a 12-parameter creation tool. It lacks context about the IPsec workflow, the dependency on a Phase 1, and the need to potentially apply changes. It does not mention relationship to sibling tools like apply_ipsec_changes, making the overall tool definition incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 12 parameters are thoroughly documented in the schema itself. The description does not add any additional parameter semantics, but the baseline of 3 is appropriate since the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is explicit: 'Create an IPsec Phase 2 (Child SA / tunnel) entry'. It clearly states the action (create), the resource (IPsec Phase 2), and clarifies the resource with a parenthetical. This distinguishes it from sibling tools like create_ipsec_phase1 or create_ipsec_phase2_encryption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like update_ipsec_phase2 or delete_ipsec_phase2. It also does not mention prerequisites (e.g., the need for an existing Phase 1) or any follow-up actions such as apply_ipsec_changes, which are important in an IPsec workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already indicating readOnlyHint=false and destructiveHint=false, the description adds no behavioral transparency beyond what is stated. It does not disclose whether the mapping takes effect immediately, how conflicts are handled, or any required permissions, despite the schema containing an apply_immediately parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words, making it concise and front-loaded. While it is terse for a tool with many parameters, the schema compensates, and there is no bloat to penalize.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters) and the presence of an output schema, the description provides only minimal context. It identifies the creation action but omits typical use cases, prerequisites, or operational notes, though the schema and annotations partially cover the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides thorough descriptions for all 13 parameters (100% coverage), so the description is not required to explain parameters. The description itself adds no additional meaning beyond the schema, matching the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create an outbound NAT mapping' clearly identifies the action (create) and the specific resource (outbound NAT mapping). This distinguishes it from sibling tools like create_nat_port_forward and create_nat_onetoone_mapping by the explicit 'outbound' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus related tools such as create_nat_port_forward or create_nat_onetoone_mapping. There are no mentions of prerequisites, alternatives, or exclusions, leaving the agent 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive mutation. The description adds no behavioral details beyond the action itself, such as immediate application or associated firewall rule creation, which are only present in schema parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundancy. It is appropriately sized for a tool whose schema carries the detailed information, and it is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a rich schema and annotations, the one-sentence description fails to explain the tool's role in NAT configuration or distinguish it from related NAT creation tools. Given 12 parameters and sibling tools, more context would be needed for an agent to confidently select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all 12 parameters with descriptions, including advanced notes (e.g., destination_port restriction). The description contributes no additional parameter semantics, so the baseline of 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'NAT port forwarding rule', which precisely identifies the tool's function and differentiates it from update/delete/search siblings with the same resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like update_nat_port_forward or create_nat_onetoone_mapping. It lacks context about inbound forwarding use cases, prerequisites, or exclusions, leaving the agent to infer 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-destructive operation. The description adds only the 'dummynet pipe' detail, which is more of a technical definition than behavioral transparency. It does not disclose what happens upon creation, whether changes take effect immediately (though an apply_immediately parameter exists), or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no fluff. It is concise and readable, and every word earns its place, including the parenthetical technical clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the rich schema and output schema, the description lacks contextual information for an 8-parameter tool. It doesn't explain the purpose of a traffic limiter in the broader system or when one would be created, making it insufficiently complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds no parameter semantics beyond the schema; it doesn't mention bandwidth, units, or mask options, leaving the schema to fully document parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (Create), the resource (traffic limiter), and adds a specific technical qualifier (dummynet pipe), distinguishing it from related tools like create_traffic_shaper. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_traffic_shaper or create_shaper_queue, nor any prerequisites or interaction with firewall rules. The description simply states what it does without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the 'create' action. Annotations indicate readOnlyHint=false and destructiveHint=false, which are consistent but not elaborated. No information is given about side effects, application of changes, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded and easy to read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the schema being thorough, the description lacks essential context about the role of traffic shaping in the broader system, when to choose this over create_traffic_limiter, and whether additional steps are needed. The existence of sibling tools like create_shaper_queue and update_traffic_shaper indicates relationships that are not explained. For a create operation with 7 parameters, this is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters have descriptions in the schema. The description does not add any parameter-specific information. According to the high-coverage baseline, this scores a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('traffic shaper') with a scope ('on an interface'), distinguishing it from sibling tools like search_traffic_shapers, update_traffic_shaper, and delete_traffic_shaper. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, relationships with shaper queues or traffic limiters, or whether this should be used with apply changes. The description is purely a definition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds no additional behavioral context, such as whether the creation is applied immediately (though the apply_immediately parameter exists) or whether a separate apply_virtual_ip_changes call is needed. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler or redundant information, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, multiple modes like CARP/ipalias, and related apply/update/delete siblings), the description is under-specified. It doesn't mention that the virtual IP must be assigned to an existing interface, or that CARP mode requires additional parameters, leaving the agent to infer from the schema. The output schema may help, but the description itself is not sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's property descriptions provide comprehensive coverage (100%), documenting all 11 parameters with details like 'VHID group number (required for CARP, 1-255)' and 'Interface to assign the VIP to (wan, lan, opt1, etc.)'. The description adds no parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('a virtual IP address'), clearly distinguishing from sibling tools like update_virtual_ip, delete_virtual_ip, and search_virtual_ips. It states exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as existing interfaces or CARP requirements. There is no context about when to prefer this over update_virtual_ip or delete_virtual_ip.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, which is ambiguous for an export operation. The description adds no behavioral context, such as whether the export triggers a download, modifies system state, or requires special permissions. It neither contradicts nor enriches the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasteful words. It is efficient but somewhat under-specified, lacking any context beyond the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists and parameters are fully documented, the description does not explain how to use the tool in practice (e.g., how to get a certificate ID, what happens with the exported output, or why it is not read-only). It is minimally complete for a simple export tool but lacks helpful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both certificate_id and passphrase already documented in the input schema. The description adds no additional parameter 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Export' with a clear resource 'certificate' and format 'PKCS#12', which distinguishes it from sibling tools like search_certificates (searching) and create_certificate (creation). It fully identifies the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as export_openvpn_client_config, or how to obtain the required certificate_id. There are no exclusions or context about typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds only 'comprehensive' and 'configuration', which doesn't provide meaningful behavioral context beyond the name and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant wording. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter introspection tool with an output schema, the description is minimally sufficient but could benefit from specifying what 'capabilities' includes (e.g., endpoints, authentication methods, feature flags).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and the schema is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves API capabilities and configuration. It distinguishes itself from sibling get_* tools that target specific settings (e.g., gateway, webgui), though 'comprehensive' is somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool or why it would be preferred over other get_* tools. The description doesn't mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, and the description merely restates the read nature ('Get') without adding any behavioral context such as return format, permissions, or side effects. It adds no value beyond the structured metadata and does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, appropriately sized for a zero-parameter getter. However, it is so minimal that it borders on under-specification, offering no additional context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read-only, zero parameters) and the presence of an output schema, the description is sufficient for an agent to select it correctly. The sibling list provides a clear update counterpart, and annotations cover the safety profile, though the description could mention what settings are included.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so the baseline is 4. There is nothing for the description to explain about parameters, and it correctly does not invent any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and a specific resource ('email notification settings'), making the tool's function clear. It distinguishes naturally from the sibling update_email_notification_settings tool via the get/update contrast, though it essentially restates the tool name without adding scope or detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no mention of update_email_notification_settings as the write counterpart, and no exclusions or prerequisites. An agent receives zero contextual direction beyond the tool's name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds no further behavioral context. It neither discloses what the settings contain nor any special behavior (e.g., caching, permissions), and simply restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is concise and directly conveys the core purpose, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple no-parameter getter with annotations and an output schema, the description is minimally adequate. However, it does not elaborate on what 'system console settings' includes, leaving some ambiguity about the return content, though the output schema covers return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score is 4. The description adds no parameter-level information, but none is needed since the schema confirms the absence of any inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'system console settings', which is specific and unambiguous. It does not explicitly distinguish from sibling get_*_settings tools, but the unique resource name prevents confusion with similar getters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as update_system_console or other settings getters. The description gives no context, prerequisites, or exclusions, leaving the agent to infer usage 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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the tool can delete records, which is destructive, but the annotations declare destructiveHint=false, creating a clear contradiction. The description also lacks additional behavioral context like the require confirm=true for delete or the effect of apply_immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose. Every word earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and output schema, the minimal description is sufficient for an agent to select the tool, though it does not explicitly differentiate from zone-level management or highlight the dual-mode nature. The schema carries the load for parameter semantics and return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing detailed meanings for all 8 parameters, including 'required for create' and 'required for delete' conditions. The tool description adds no extra parameter-level information, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Create or delete a DNS record within a BIND zone'. It clearly states the tool's function and differentiates from siblings like create_bind_zone (zone-level creation) and search_bind_zone_records (record listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions or references to related tools such as search_bind_zone_records or manage_bind_access_list, leaving the agent to infer usage from the bare description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says it removes an allowed IP (a destructive operation) while the annotations set destructiveHint to false. This is a direct contradiction, and the description adds no further behavioral context beyond the fact of add/remove. No mention of the confirm safety gate or apply behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It immediately states the verb and resource, fitting the ideal compact description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters and an output schema, the description is too minimal. It omits critical operational details like the mandatory confirm=true for delete operations, and does not mention how changes are applied (apply_immediately or separate apply_wireguard_changes). The annotation contradiction further undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% descriptive coverage for all 7 parameters, including the action values, required IDs, and the confirm gate. The description only reiterates the high-level operation and does not add parameter-level detail, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add or remove an allowed IP for a WireGuard peer' uses a specific verb pair (add/remove) and names the exact resource (allowed IP for a WireGuard peer). It clearly distinguishes from sibling tools like search_wireguard_peer_allowed_ips and manage_wireguard_tunnel_address.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying allowed IPs, but it does not explicitly state when to use it versus alternatives like search_wireguard_peer_allowed_ips. It gives a clear context for the operation but lacks exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the basic safety profile. The description adds no additional behavioral context such as whether it returns only enabled configurations, how pagination works, or whether a server_id is required for filtering. It merely restates the search intent without enriching the behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is easy to scan and front-loads the verb and object. It contains no fluff or repetition. While it could be slightly more informative, it is appropriately sized for a simple search operation and does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and 100% parameter documentation, the description covers the essentials for a search tool. However, it lacks context about its relationship to the sibling export_openvpn_client_config and does not explain when a user would need this search. The existence of many related search/export tools makes this missing guidance a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with all four parameters described adequately. The description does not add parameter-specific meaning beyond the schema, which is acceptable for a well-documented schema. The word 'available' hints at filtering but is too vague to count as added semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('OpenVPN client export configurations'), clearly distinguishing it from sibling tools like export_openvpn_client_config (which exports) and search_openvpn_clients (which searches clients, not configs). The phrase 'available' adds scope, implying a read-only listing of what can be exported.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of using this search to find configurations before exporting, nor any exclusion criteria. The description is purely a statement of action with no contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations and schema. It does not disclose that enabling maintenance mode sets all VIPs to backup or that apply_immediately may trigger an immediate failover. Annotations indicate non-destructive and idempotent, but the description itself is silent on side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and target. There is no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with well-documented schema and annotations, and an output schema exists. The description adequately states its purpose, but lacks usage guidance and behavioral disclosure, which lowers completeness slightly. Overall, the structured data compensates for the brevity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not discuss parameters, but the input schema provides clear meanings for enable, maintenance_mode, and apply_immediately, so no additional description is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the target ('CARP maintenance mode settings'), distinguishing it from read-only siblings like get_carp_status. However, it does not elaborate on which specific settings are updated, though the schema covers that.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool vs alternatives, nor does it give any context about maintenance operations or related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the annotations (readOnlyHint=false, idempotentHint=true) by indicating a write operation. It adds no behavioral details beyond the structured annotations, such as apply_immediately semantics or the requirement that gateway names must exist, though the parameter schema partially covers these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no filler words, making it front-loaded and easy to read. It is concise but borders on under-specification, conveying only the basic action without additional useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's relative simplicity and the rich schema/annotations, the description is minimally complete. However, it lacks any context about when to prefer this tool over adjacent gateway-related tools, which reduces the agent's ability to select it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with clear descriptions for all three parameters, including allowed values and constraints. The description adds no additional meaning beyond what the schema already states, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('default gateway settings'), so the core purpose is understandable. However, it is somewhat generic and does not explicitly distinguish this tool from siblings like update_gateway or explain that it sets the default IPv4/IPv6 gateway identities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as update_gateway, get_default_gateway, or apply_routing_changes. No prerequisites, exclusions, or recommended contexts are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond restating the purpose, such as whether it performs partial updates, how apply_immediately affects changes, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant words. It is concise and front-loaded with the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the schema and annotations are rich, the description is minimal. It fails to explain important usage context such as the default behavior of apply_immediately (true) and whether an explicit apply_dhcp_changes call is needed after updating. For an update tool with this complexity, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 5 parameters (100% coverage), including option_id referencing search_dhcp_custom_options. The description adds no additional parameter meaning, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Update' and resource 'DHCP custom option' with identifier 'by ID', making the tool's purpose clear. It also distinguishes from sibling tools create/delete/search for DHCP custom options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create or delete. It also does not mention prerequisites such as obtaining an existing option_id from search_dhcp_custom_options, or whether apply_dhcp_changes needs to be called afterwards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Update' and adds no behavioral context beyond what the name implies. It does not disclose partial-update semantics (e.g., whether omitted fields are preserved), the effect of apply_immediately, or error behavior when the client is not found. Annotations indicate idempotent and non-destructive, but the description itself provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It is clear and efficient, though it could benefit from a brief note on update behavior without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and annotations present, the tool is minimally usable, but the description leaves ambiguity about how partial updates work and what apply_immediately does. An agent might not know whether to include null fields or how the update applies, which is a notable gap for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already described. However, the description does not clarify key update nuances, such as whether passing null for an optional field clears it or leaves it unchanged. It relies entirely on the schema, which is adequate but not enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update', the resource 'FreeRADIUS client', and the scope 'by ID'. This distinguishes it from create, delete, and search tool siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention that the client must already exist, that client_id should come from search_freeradius_clients, or how it differs from create_freeradius_client.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral detail beyond the action itself. Annotations indicate readOnly=false, idempotent=true, and destructive=false, but the description does not add context about side effects (e.g., service restart, persistence, or relationship to apply_immediately).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence with no filler. It is front-loaded with the core action and resource, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the description is minimal, the combination of full schema coverage, output schema, and annotations (idempotent, non-destructive) provides sufficient context for an agent to invoke the tool correctly. Some additional context about applying changes could be useful, but not necessary given the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all three parameters with complete coverage (dnsserver, dnslocalhost, apply_immediately). The description adds no additional parameter semantics, so it earns the baseline score of 3 for good schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates system DNS server settings, using a specific verb and resource. It distinguishes from sibling getters like get_system_dns and other DNS tools by focusing on the system-wide DNS server configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives such as update_dns_resolver_settings or get_system_dns. It lacks context about prerequisites, exclusions, or scenario-based recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already provide. It does not disclose that changes may require an apply step, nor does it mention the behavior of apply_immediately. With readOnlyHint=false and destructiveHint=false already signaling a mutation, the description merely repeats the obvious 'update' action without additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and target. It contains zero superfluous words and is instantly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a rich schema and output schema, the description omits crucial operational context: how to discover existing IDs, whether changes apply immediately or require separate apply action, and any prerequisites (e.g., a VIP must already exist). For a mutating tool with 12 parameters, this is insufficiently contextualized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 12 parameters. The description adds no extra semantics beyond identifying the required vip_id. This meets the baseline for schema-covered parameters but does not enhance understanding of parameter relationships or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing virtual IP by ID' uses a specific verb ('Update') and resource ('virtual IP'), clearly distinguishing it from sibling tools like create_virtual_ip, delete_virtual_ip, and search_virtual_ips. The 'by ID' qualifier precisely defines the operation scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that vip_id should come from search_virtual_ips, nor does it clarify the relationship with apply_virtual_ip_changes or the apply_immediately parameter. The description solely states the action without any usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose read-only=false, idempotent=true, and destructive=false. The description adds no extra behavioral context such as side effects, application timing, or whether changes are immediately active, merely restating the action without going beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a front-loaded verb and zero filler, making it appropriately concise for a simple tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 10 optional parameters, this description is too terse. It does not clarify whether unspecified fields are left unchanged or reset to null, nor does it mention the apply_immediately behavior that affects when changes take effect. Even with an output schema present, the update semantics remain ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 10 parameters have schema descriptions (100% coverage), so the schema carries the semantic load. The description adds no parameter semantics beyond 'by ID', which is already covered by the required peer_id parameter, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' and clearly identifies the resource as an existing WireGuard peer by ID, distinguishing it from create, search, and delete sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying existing peers but does not explicitly state when to use this over create/delete or mention prerequisites like searching for the peer ID first. The 'by ID' hint is present but no explicit context or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond the annotations. It does not disclose requirements like the existence of a valid Certificate Authority reference (caref) or what happens if a CRL already exists for the CA. The annotations already indicate a non-readonly, non-destructive operation, but the description itself contributes no extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. It is appropriately brief for a simple create operation, though it could include additional context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema documents all parameters and an output schema exists, the description lacks important context such as dependency on an existing CA, whether creating a CRL affects existing resources, and any post-creation steps. The tool has moderate complexity and would benefit from additional guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides concise descriptions for all four parameters, including caref and descr, with 100% coverage. The description does not mention parameters but does not need to, as the schema already defines them clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a Certificate Revocation List (CRL) on pfSense' uses a specific verb and resource, clearly distinguishing this from sibling tools like update_crl, delete_crl, and search_crls. It is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is for creating a CRL but does not mention when to use it versus alternatives such as update_crl or delete_crl. There is no explicit guidance on prerequisites or exclusions, so the agent must infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds no additional behavioral context such as whether apply_immediately defers changes, validation behavior, or overlap handling. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It front-loads the action and resource, making it immediately actionable and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With complete schema coverage, annotations, and an output schema present, the description is minimally sufficient for a simple create operation. However, it lacks usage context such as when to call apply_dhcp_changes or how apply_immediately interacts with the broader change workflow, leaving it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so a baseline of 3 is appropriate. The description adds minimal value beyond the schema, merely reinforcing that the pool belongs to an interface, but it does not clarify range semantics or apply_immediately 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create', identifies the exact resource 'DHCP address pool', and adds scope with 'for an interface'. It clearly distinguishes this from sibling update/delete/search_dhcp_address_pool tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, no prerequisites are mentioned, and there is no mention of related tools like apply_dhcp_changes or create_dhcp_static_mapping. The agent receives only a bare purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a non-read-only, non-destructive write operation. The description adds no further behavioral context such as whether apply_immediately controls activation, duplicate handling, or effects on existing DHCP reservations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with a useful parenthetical clarification. It contains no filler or redundant words, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and annotations cover parameters and safety basics, the description lacks high-level context such as when to choose this tool, prerequisites (e.g., existing interface/DHCP pool), or the implications of apply_immediately=false requiring a subsequent apply_dhcp_changes. The presence of an output schema helps with return values, but these gaps make it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all 9 parameters, including defaults and examples. The description itself adds no parameter-level detail, so with high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a DHCP static mapping (reservation)' uses a specific verb and resource, clearly stating the tool's purpose. It distinguishes from sibling tools by action (create vs update/delete/search) and by resource (static mapping vs DHCP address pool).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites, or interaction with apply_dhcp_changes. The description merely states the action, leaving usage to be inferred from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The tool is annotated as not read-only and not destructive, but the description adds no additional behavioral context. It does not mention side effects, persistence, or the need to apply routing changes, leaving the agent without information on what happens after creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, front-loading the core action. It is efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and output schema cover parameters and return values, the description is very thin. For a tool with nine parameters and routing implications, it would benefit from context about the gateway's role and any follow-up actions, but the existing schema mitigates some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage across all nine parameters, so the schema fully documents parameter semantics. The description adds nothing beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description "Create a routing gateway" uses a specific action verb and clearly identifies the resource. It distinguishes from sibling tools by naming the resource type and the create action, differentiating from update_gateway, delete_gateway, and create_gateway_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus other gateway-related tools such as update_gateway or search_gateways. It only states the function without any context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), but the description does not disclose side effects like whether changes are applied immediately (apply_immediately parameter) or if a separate apply step 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and free of unnecessary words. It effectively communicates the core purpose without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, output schema, and annotations), the description is minimal. The schema covers parameter semantics, but the description does not mention important operational aspects such as involving backend servers (manage_haproxy_backend_server) or the apply_immediately flag. It is adequate for a simple create but lacks broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are documented in the schema. The description itself adds no parameter-specific meaning beyond what the schema already provides, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create an HAProxy backend pool' uses a specific verb and resource, clearly distinguishing this from sibling tools like search_haproxy_backends, update_haproxy_backend, and delete_haproxy_backend. It unambiguously states the action and object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives. It does not mention prerequisites, when not to use, or that this is for creating a new backend rather than modifying an existing one. Usage is only implied by the verb 'Create'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already indicate this is a mutating (readOnlyHint=false) but non-destructive (destructiveHint=false) operation, the description adds no additional behavioral context. It does not disclose prerequisites (e.g., existing CA/cert), whether the OpenVPN service is restarted, or the effect of apply_immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no fluff, front-loading the verb and object. Every word is necessary and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 22 parameters and an output schema, the description is minimal. It does not explain prerequisites or relationships with sibling OpenVPN tools, though the schema covers the input parameters comprehensively. It is adequate but lacks context about when this tool is appropriate in a broader workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 22 parameters have descriptions in the schema (100% coverage), which meets the baseline for high schema coverage. The tool description itself does not add any parameter-level information, but the schema is sufficiently self-documenting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Create' and the resource 'OpenVPN client instance', which uniquely identifies this action and distinguishes it from sibling tools like update_openvpn_client, delete_openvpn_client, and create_openvpn_server.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of the relationship to update_openvpn_client, delete_openvpn_client, or create_openvpn_server, leaving the agent to infer 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds no additional behavioral context. It only restates 'Create' without disclosing side effects like immediate application or configuration changes. No extra value beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero filler. It is immediately clear what the tool does, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 9 parameters and an output schema, yet the description is minimal. It does not explain the parent-child relationship between shaper and queue, nor the behavior of apply_immediately. It is adequate but leaves clear gaps in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 9 parameters, so the schema fully documents each field. The description adds no parameter-specific meaning, but the baseline of 3 is appropriate when schema covers everything.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource combination ('Create a traffic shaper queue'), clearly distinguishing this tool from siblings like search_shaper_queues, update_shaper_queue, delete_shaper_queue, and create_traffic_shaper. It unambiguously states the action and object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it requires an existing parent shaper (parent_id) or how it relates to create_traffic_shaper. There is no 'use when...' or exclusionary language.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context beyond what the name implies—no mention of what 'version information' includes, whether it performs a network call, or if it might return multiple version components. This is minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no fluff. It front-loads the verb and resource immediately, and every word is necessary. It is appropriately sized for a simple zero-parameter getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params) and the presence of an output schema (which covers return structure), the description is sufficient for an agent to know what it does. One could argue it could mention whether this returns both pfSense and underlying OS version, but the output schema likely covers that. The description is complete enough for the operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is trivially 100% covered. With no parameters, the description does not need to add anything. Baseline 4 applies because there are no parameter semantics to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('pfSense system version information'), clearly identifying what the tool does. It distinguishes from siblings like get_system_hostname or get_system_timezone, though it does not enumerate the exact fields returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description merely restates the function without any context such as 'use this to check the current firmware version' or exclusions. Since there are many sibling getter tools, this lack of differentiation hurts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'remove an alias', which is a destructive operation, yet annotations set destructiveHint=false. This is a direct contradiction. The description adds no further behavioral context beyond what annotations already claim.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the action and resource. Every word earns its place, and there is no repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema richly documents parameters and an output schema exists, so the description doesn't need to explain return values. However, the annotation contradiction creates ambiguity about destructive behavior, and the description could have noted the confirm safety gate or create/delete parameter requirements, making completeness only barely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add any parameter-level detail, only a high-level summary of the operation. It neither compensates for nor detracts from the schema's rich parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Add or remove') and a clear resource ('an alias for a DNS Forwarder host override'). This clearly distinguishes it from sibling tools like create/update/delete host override or search aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (adding or removing an alias) but does not mention alternatives or exclusions. It omits explicit conditions for using create vs delete, though the schema hints at these.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral details beyond the annotations. It does not mention that delete operations require the 'confirm' safety gate, that apply_immediately defaults to true, or that removal is destructive. Given the tool's dual create/delete nature, this lack of disclosure 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded and easy to parse. However, given the tool's two distinct modes (create and delete), it could be better structured to separate the actions without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters and dual create/delete behavior, a one-sentence description is insufficient. It does not explain which parameters are required for each action (e.g., server_id for delete, timeserver for create) or that confirm must be true for delete. The description relies entirely on the schema for operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds no additional clarity about parameter semantics; it only summarizes the action. The schema descriptions already cover the create vs. delete parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Add or remove' and clearly identifies the resource 'NTP time server', distinguishing it from sibling tools like search_ntp_time_servers and get_ntp_settings. It precisely communicates the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying the NTP server list ('add or remove') but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. It leaves the usage context to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description provides no behavioral detail beyond the action verbs. It does not mention the confirmation safety gate for delete operations, the difference between create and delete parameters, or the apply_immediately behavior. Annotations claim destructiveHint: false, but the tool's delete operation is destructive, creating a contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. It is appropriately concise for a tool with a rich schema, though it could benefit from a brief usage hint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is fairly complex with two distinct operations (create/delete) and a safety gate parameter. The description is very sparse, relying entirely on the schema for details such as the confirm requirement and watchdog_id vs name. Given the presence of an output schema and 100% parameter coverage, it is minimally complete but lacks operational context that would help an agent select it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter-level detail beyond the input schema. The schema provides full descriptions for all six parameters, including the required confirm flag for deletions. The description's high-level wording does not enhance the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add or remove a service watchdog entry' clearly states the tool's function with specific verbs (add/remove) and resource (service watchdog entry). It distinguishes from sibling tools like search_service_watchdogs, which is read-only, while this is a mutation tool. This is a clear, non-tautological purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating and deleting watchdog entries but does not explicitly state when to use it versus alternatives. There is no mention of prerequisites, or a direct reference to search_service_watchdogs for listing. However, the action parameter clarifies the two operation modes, providing some implied guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and 'Search' is consistent with those. However, the description adds no additional behavioral context such as pagination behavior, result format, or search scope beyond the resource name. It does not contradict the annotations, but also provides no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded with the primary action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward search operation with a rich output schema and annotations covering safety. The description is minimally adequate but does not mention that search_term is a client-side filter or that results are paginated; while the schema covers these details, the description itself offers little contextual richness beyond the purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters already well-documented (page, sort_by, page_size, search_term). The description adds no parameter-level semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' and a specific resource 'BIND access control lists', which clearly distinguishes it from sibling tools like search_dns_access_lists and manage_bind_access_list. It fully states what the tool does with precise scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as search_dns_access_lists or manage_bind_access_list. The name implies usage for searching BIND ACLs, but there are no exclusions, prerequisites, or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the read-only and non-destructive nature. The description adds only that filtering and pagination are supported, which is also evident from the schema parameters. No further behavioral traits are disclosed, but the annotations carry the safety burden, so this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the core purpose. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema, output schema, and annotations, the description is minimally adequate. However, it lacks any context about how this tool differs from very similar siblings like 'search_dns_forwarder_host_overrides', which would be valuable for an agent navigating a large toolset.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with each of the 6 parameters already documented in detail. The description itself adds no parameter-specific semantics beyond the schema's existing information, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and the resource 'DNS host overrides', with an additional scope of 'filtering and pagination'. It does not explicitly differentiate from similar sibling tools like 'search_dns_forwarder_host_overrides', but the resource name is specific enough to distinguish in most contexts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus similar search tools, nor any exclusions or alternatives. The generic phrase 'with filtering and pagination' does not help an agent choose between this and related DNS search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read behavior is clear. The description adds minimal context beyond the annotations, only hinting at advanced search/filter capabilities without detailing behavior like pagination or result structure, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loads the main action, and contains no redundant words. It is appropriately sized for a simple search tool, though the 'advanced options' phrase is slightly vague but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with an output schema and annotations covering safety, but the description lacks differentiation from sibling tools and clarifications about what 'advanced options' means. This makes the description minimally viable but not fully complete for an agent to confidently select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully documented with descriptions. The description's mention of 'advanced options' does not add additional meaning beyond what the schema already 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches and filters network interfaces, which is a specific verb+resource pair. However, the phrase 'advanced options' is vague and does not distinguish this tool from sibling search tools like search_interface_configs or find_interfaces_by_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_available_interfaces or find_interfaces_by_status. It also does not mention any exclusions or prerequisites, leaving the agent to infer usage from the vague 'advanced options'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the behavioral detail that the tool supports filtering and pagination, which is consistent with the annotations and schema. However, it does not disclose additional behavior such as result limits, relationship to parent tunnel, or output shape—though the output schema exists to cover return values. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Search WireGuard tunnel addresses with filtering and pagination.' It states the verb and resource immediately with no filler, redundant phrasing, or unnecessary clauses. Every word contributes to meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 optional parameters fully documented in the schema, an output schema present, and read-only annotations provided, the description covers the basics. However, it leaves the tool's relationship to sibling WireGuard tools unexplained—specifically the distinction between tunnel addresses and peer allowed IPs (search_wireguard_peer_allowed_ips), and the role of parent_id. This is adequate but has clear gaps for an AI agent choosing among many similar WireGuard tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (page, sort_by, page_size, parent_id) are already documented in the schema. The description's mention of 'filtering and pagination' echoes these parameters without adding new meaning, so the baseline of 3 applies. It does not clarify the semantics of parent_id (e.g., whether it refers to a tunnel ID) or sort_by values beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') with a specific resource ('WireGuard tunnel addresses'), and the plural 'addresses' distinguishes it from the singular manage_wireguard_tunnel_address and from search_wireguard_peers/search_wireguard_tunnels. However, it does not explicitly state what 'tunnel addresses' refers to or name the alternatives, leaving some ambiguity about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that manage_wireguard_tunnel_address handles modifications, that search_wireguard_peer_allowed_ips covers peer allowed IPs, or when to prefer this search over related WireGuard queries. The only hint is 'filtering and pagination,' which implies a list/search context but is not an explicit usage directive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which already convey the core safety profile. The description adds no behavioral context beyond 'Update,' such as potential service disruption, the role of apply_immediately, or whether changes are staged. It does not contradict annotations, but it provides no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded with the verb and resource. It contains no filler or redundant information, making it highly concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and complete parameter descriptions, the tool is functionally usable from structured data alone. However, the description lacks high-level context about effects, such as whether changes require a service restart or how apply_immediately impacts behavior, making it adequate but not fully comprehensive for a 7-parameter settings update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 7 parameters (enable, listen_on, rate_limit, log_severity, forwarder_ips, apply_immediately, dnssec_validation), achieving 100% schema description coverage. The description adds no extra parameter semantics, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update BIND DNS server settings,' which clearly specifies the verb (update), resource (BIND DNS server), and scope (settings). This distinguishes it from zone-specific operations such as update_bind_zone, and from other DNS update tools like update_dns_resolver_settings or update_dns_forwarder_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that get_bind_settings should be used for reading current settings or that update_bind_zone is for zone configuration. The description simply states the action without contextual prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is a non-read-only, idempotent, non-destructive update, so the description does not need to convey safety. However, the description adds no details beyond the obvious 'update' action—it does not clarify whether the operation is a partial update, whether setting a field to null clears it, or whether changes require an additional apply step. This leaves behavioral gaps despite the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately identifies the action, resource, and key differentiator. Every word contributes meaning, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter update tool with a valid output schema and annotations, the description is minimally adequate but lacks important behavioral context about update semantics (e.g., whether null clears a field, whether it is a partial update). The schema covers identifiers and field types, but the description does not fully orient an agent on how to invoke it correctly beyond the basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for each parameter (crl_id, descr, lifetime), so the description does not need to duplicate that. The baseline of 3 applies because the schema carries the parameter semantics; the description itself adds no parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action ('Update') on a specific resource ('Certificate Revocation List (CRL)') and identifies the key selector ('by ID'). This distinguishes it from sibling tools like create_crl, delete_crl, and search_crls, 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying an existing CRL identified by ID, but it does not explicitly state when to use it versus alternatives or mention prerequisites like searching for the CRL first. The input schema's reference to 'array index from search_crls' adds guidance, but that is outside the description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, covering the mutation and safety profile. The description adds only that the list must already exist but does not disclose other behavioral aspects such as the impact of apply_immediately or whether the operation is a partial update (only provided fields). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 7-word sentence, front-loaded with the verb and target. Every word is informative, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The combination of full schema coverage, appropriate annotations, and an output schema covers much of the context needed. However, the description omits practical guidance such as how updates affect the existing list and whether changes are applied immediately or require a separate apply action, making it only moderately complete for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a clear description in the input schema (e.g., aclaction lists allowed values, apply_immediately explains its effect). The description itself adds no parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Update') and the target resource ('existing DNS Resolver access list'), distinguishing it from sibling tools like create_dns_access_list and delete_dns_access_list. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_dns_access_list or search_dns_access_lists, nor does it mention prerequisites like the access list needing to exist before updating. There is no indication of when to apply changes or that apply_dns_resolver_changes should follow if apply_immediately is false.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral traits beyond what annotations already communicate (non-readonly, idempotent, non-destructive). It doesn't describe side effects like whether changes require an apply step, though the apply_immediately parameter in the schema hints at it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, clear and front-loaded, no filler. Every word earns its place and the description is efficiently minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with well-documented schema and an output schema present. The description is adequate for a straightforward update, but relies heavily on schema and annotations for context; it doesn't describe behavior when only ID is provided or whether changes are staged.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with descriptions for each parameter, so baseline 3 is appropriate. The description adds no parameter semantics beyond 'by ID', but the schema fully documents the fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'update' and resource 'firewall schedule' with 'by ID', clearly distinguishing it from create/delete/search siblings. It precisely states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or alternative guidance is provided. The description does not mention that schedule_id should come from search_firewall_schedules or when to prefer this over create/delete. It lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds no further behavioral context, such as the effect of 'apply_immediately' or any prerequisite steps like calling apply_ipsec_changes. It merely restates the action without enriching annotation data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is immediately comprehensible. It front-loads the action and resource. However, it may be overly terse for a tool with 7 parameters and an apply step, leaving out potentially valuable context while still being structurally clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a complex mutation tool. It does not mention that changes may require an explicit apply operation (like apply_ipsec_changes) or that the 'apply_immediately' parameter can enforce immediate application. It also does not tell the agent to first search for the encryption ID using search_ipsec_phase2_encryptions. While an output schema exists, the description should still orient the agent on lifecycle and prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters, each with clear descriptions (e.g., 'encryption_id', 'apply_immediately', 'dhgroup'). The description's only parameter hint is 'by ID', which matches the required encryption_id field. Since schema coverage is complete, the description does not need to add much, but it also does not add any extra context about parameter usage or interdependencies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource type (IPsec Phase 2 encryption entry), and the selection mechanism (by ID). It distinguishes this tool from sibling tools like create_ipsec_phase2_encryption, delete_ipsec_phase2_encryption, and update_ipsec_phase2, all of which are present in the sibling tool list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing ... by ID' implies the entry must already exist and its ID is needed, which hints at using a search tool first. However, the description does not explicitly mention when to use this tool versus create/delete alternatives, nor does it mention the need to apply changes after updating (e.g., via apply_ipsec_changes).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (idempotentHint=true, destructiveHint=false), so the description need not repeat that. However, it adds no additional behavioral context such as partial update semantics, failure conditions, or the role of apply_immediately. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that front-loads the action and object. Zero redundant words, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema, annotations, and output schema, the description is adequate but not thorough. It does not clarify that unspecified fields remain unchanged or provide any workflow hint like obtaining the queue ID via search_shaper_queues. For an update tool, this is a moderate level of completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter (e.g., bandwidthtype, qlimit, apply_immediately) already documented. The description itself adds no parameter detail, but per the baseline for high schema coverage, this is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Update'), identifies the resource ('shaper queue'), and specifies scope ('existing...by ID'). This distinguishes it from sibling tools like create_shaper_queue and delete_shaper_queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no mention of obtaining queue IDs via search_shaper_queues, and no exclusions. The only information is the action itself, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate non-read-only, idempotent, and non-destructive behavior, but the description adds no additional context. It does not disclose partial-update semantics, whether changes apply immediately, or what happens on failure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy, front-loaded with the verb and object. It is appropriately concise and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple and the schema and output schema exist, but the description omits important context such as whether the update is partial (only provided fields changed) and the role of apply_immediately or apply_routing_changes. It is adequate but leaves gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 6 parameters are already well-described in the input schema. The description adds no parameter semantics, but the baseline of 3 applies due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('static route') with an identifier ('by ID'), clearly distinguishing it from create/delete/search siblings. It accurately states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites like obtaining the route_id from search_static_routes, nor does it explain when to use create/delete/apply routing changes instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already state (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It fails to disclose potential side effects like network reconnection or the need for a reboot after changing the hostname, which is significant for this mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that directly communicates the tool's purpose. It contains no filler or redundant content, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema fully documents all parameters and an output schema exists, the description itself lacks guidance on when to apply changes immediately, potential side effects, or how this tool interacts with related read tools. It is adequate for a simple update but leaves contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description mentions hostname and domain but adds no additional semantic detail beyond what the parameter descriptions already provide. It does not clarify relationships between parameters, such as whether both can be null or the effect of apply_immediately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Update the system hostname and/or domain'. It identifies the resource and the operation, and distinguishes this from read-only siblings like get_system_hostname.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives, prerequisites, or post-update verification steps. It does not mention that get_system_hostname can be used to read current values, nor does it explain when apply_immediately should be true or false.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating (readOnlyHint: false), idempotent (idempotentHint: true), non-destructive (destructiveHint: false) operation. The description adds no behavioral context beyond 'update', such as whether changes require a reboot, how apply_immediately affects application, or what happens if the tunable does not exist. It is consistent with annotations but does not enrich them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence: 'Update an existing system tunable by ID'. It is front-loaded and contains no filler or redundant wording. Every word contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, full schema descriptions, and annotations, the description is minimally adequate but leaves gaps. It does not mention how to obtain the tunable_id (beyond schema), when changes take effect, or any special considerations like apply_immediately handling. It is sufficient for a well-schema'd tool but lacks the richer context typically needed for mutating operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description itself adds no parameter-level meaning; it only mentions 'by ID' which is already captured in the tunable_id parameter description. The schema's description for tunable_id usefully references search_system_tunables, but the tool description contributes nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing system tunable by ID' uses a specific verb (update) with a clear resource (system tunable) and identifies the key parameter (ID). It effectively distinguishes this tool from create/delete/search siblings by indicating it modifies an existing entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like create_system_tunable or delete_system_tunable. While the verb 'update' implies existing entities, there is no mention of prerequisites, exclusions, or when to prefer this over other update tools. It leaves usage entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is tautological, essentially restating the tool name. It adds no behavioral context beyond what annotations provide (idempotentHint=true, destructiveHint=false). There is no mention of how updates are applied, whether they affect running config, or implications of the apply_immediately parameter. No contradiction with annotations, but no added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It immediately states the primary action and target. This is appropriate for a simple update tool and adheres to the principle that every sentence should earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but paired with a fully documented schema, annotations (idempotent, non-destructive), and an output schema. It lacks context about when to apply changes or how the update interacts with the running system, but for a basic CRUD operation, the structured fields cover most essential information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 8 parameters having individual descriptions. The tool description itself adds no parameter semantics, but the baseline of 3 applies because the schema handles parameter documentation. The 'by ID' hint repeats shaper_id's schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update an existing traffic shaper by ID.' It uses a specific verb ('Update') and resource ('traffic shaper'), and the phrase 'existing... by ID' distinguishes it from create/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus create/delete or search operations. It does not mention prerequisites like needing an existing shaper ID obtained from search_traffic_shapers, nor does it suggest alternatives. Usage is only vaguely implied by the word 'existing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations indicate readOnlyHint=false and destructiveHint=false, so it is understood as a non-read, non-destructive operation. The description consistently states 'Create', but it does not disclose any additional behavioral traits such as what happens to existing keys, whether it registers with the ACME server, or any side effects. This is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose. It is well-structured and front-loaded, with no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (5 parameters, output schema available) and full schema coverage, the description is mostly complete. However, it does not clarify the difference from 'register_acme_account_key' or explain when to use this tool over that one, leaving a minor contextual gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all 5 parameters, with each parameter having a description. The tool description itself does not add any additional parameter semantics beyond what's already in 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Create') on a specific resource ('ACME account key') with context ('for Let's Encrypt'). However, it does not differentiate from the sibling tool 'register_acme_account_key', which may perform a very similar operation, so it falls short of full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'register_acme_account_key' or other ACME-related tools. There is no mention of prerequisites, limitations, or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, indicating this is a write operation. The description adds no behavioral context beyond that, such as how apply_immediately works, whether changes require an apply step, or whether duplicates are allowed. 'NAS device' is a semantic clarification, not a behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and object. Every word earns its place, with no unnecessary detail or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations, a fully documented schema, and an output schema, the description is sufficient for a simple create operation. It lacks only optional context about lifecycle steps like applying changes, but this is not a significant gap given the apply_immediately parameter covers it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 5 parameters individually described, including an example for 'ip'. The description itself adds no parameter-level details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses 'Create' as a specific verb and 'FreeRADIUS client (NAS device)' as the resource, which is unambiguous. The verb 'Create' clearly distinguishes from sibling tools like search_freeradius_clients, update_freeradius_client, and delete_freeradius_client.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as whether to search for an existing client first or use update_freeradius_client for modifications. The only implied usage is the verb 'Create', with no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive with readOnlyHint=false, so the description doesn't need to state that it's a write operation. It adds the explicit warning that the operation is irreversible, which is a meaningful behavioral trait beyond a generic destructive flag. However, it does not mention side effects on dependent resources or the confirm/dry-run flow (though the schema covers those).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first delivers the core action, the second a necessary warning. There is no redundant phrasing or unnecessary context, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description is adequate: it states the action and warns about irreversibility, while the schema fully explains parameters and the output schema presumably documents return values. It does not cover when to use this versus sibling tools, but that gap is relatively minor given the tool's simplicity and the strength of the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all four parameters with descriptions, achieving 100% coverage. The description mentions only the 'by ID' aspect, which maps to the shaper_id parameter, but doesn't add further semantic detail. The schema's descriptions for confirm and dry_run already provide safety-gate and preview semantics, so the description offers no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Delete') and target resource ('traffic shaper') with the scope of deletion by ID. It is clear but does not explicitly compare with related tools like update_traffic_shaper, so it doesn't fully differentiate in-text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or in what scenario this is the appropriate tool is offered. The irreversibility warning is a caution but not guidance about when to choose deletion over updating or alternatives. The needed prerequisite of obtaining the ID via search appears in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the behavioral detail of pagination, but does not disclose other traits like sorting behavior or response format beyond what annotations and schema provide. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, 'Get configuration history revisions with pagination', with no wasted words. It is front-loaded with the action and resource, making it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read operation with an output schema present, so the description need not explain return values. The schema fully documents the parameters. The description could have noted that it lists multiple revisions or pointed to get_config_revision for single-revision access, but this is a minor gap given the simplicity and annotation coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions for page, sort_by, and page_size. The description's mention of pagination aligns with the page/page_size parameters but adds no additional semantic value beyond the schema. The baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as retrieving configuration history revisions and explicitly notes pagination support, using the specific verb 'Get' and resource. While it doesn't explicitly contrast with sibling tools like get_config_revision or compare_config_revisions, the name and context make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_config_revision for a single revision or compare_config_revisions for comparisons. It only states what the tool does, leaving the agent to infer the appropriate use case from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is partially known. However, the description adds no behavioral context beyond the raw action; it does not mention the confirm safety gate, apply_immediately behavior, or potential side effects. It relies entirely on schema annotations, leaving the agent without insight into execution nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It communicates the core function efficiently and earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the output schema and annotations, the description is too sparse for a dual-action management tool with 7 parameters. It omits critical operational context such as the requirement for confirm on delete, the meaning of apply_immediately, and any preconditions or side effects. The agent has to infer everything from the schema, which is incomplete without usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 7 parameters having descriptions. The tool description does not add any parameter-level semantics beyond what the schema provides, so the baseline of 3 applies. It neither helps nor hinders parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb and resource: 'Create or delete a BIND access control list.' This explicitly names the supported actions (create/delete) and the resource type (BIND ACL), distinguishing it from read-only sibling tools like search_bind_access_lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the two actions, but does not explicitly state when to choose this tool over alternatives or provide exclusions. It lacks guidance about the confirm requirement for delete or when to use related tools like create_dns_access_list, though the dual action gives some context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Search' action is consistent with that. However, the description adds no additional behavioral context such as whether results are paginated (already in schema) or if any special permissions are needed. It's adequate but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Search aliases with advanced filtering options.' No filler or redundancy. It earns its place by stating the core function, though it's minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% coverage) and presence of an output schema, the description doesn't need to detail return values or parameters. It sufficiently identifies the tool's purpose. However, it lacks any contextual notes about scope or edge cases, so it's slightly incomplete compared to the get_calls example, but still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all six parameters (page, sort_by, page_size, alias_type, search_term, containing_ip). The description's 'advanced filtering options' vaguely references these but adds no detail beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and resource 'aliases', clearly identifying the tool's operation. It's distinct from sibling CRUD tools (create_alias, update_alias, delete_alias) and other search tools by resource type. However, it doesn't elaborate on what 'advanced filtering options' entails, making it slightly generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It doesn't mention that this is the appropriate tool for finding aliases by various criteria, nor does it exclude cases like searching within alias addresses (manage_alias_addresses). Lacks explicit when/when-not instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds little beyond confirming the read-only nature via 'Search'. It does not disclose pagination behavior or other operational details, but for a simple search tool with annotations, this is acceptable. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words: 'Search certificates configured on pfSense with optional filtering'. It efficiently communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with full schema descriptions, annotations, and an output schema, the description is sufficiently complete. It does not explicitly disambiguate from ACME certificates, but the resource keyword and schema are adequate for the typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, including search_term, page, and page_size. The description's phrase 'optional filtering' adds no new meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches certificates configured on pfSense, using the specific verb 'Search' and resource 'certificates'. It is distinguishable from sibling tools like search_certificate_authorities or search_crls based on resource, though it does not explicitly mention those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus alternatives. 'With optional filtering' only hints at the mechanism, not the context or exclusions. There is no mention of when to prefer search_certificates over search_acme_certificates or other search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds mention of filtering and pagination but does not disclose additional behavioral details like response format, limits, or side effects, which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the tool's purpose. No fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is an output schema, so return value details are not needed. The description clearly names the resource (DNS Forwarder host overrides) and mentions core features (filtering and pagination). Minor gap: no explicit clarification against the similar search_dns_host_overrides tool, but the resource name is specific enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully documents all four parameters. The description adds no extra parameter semantics beyond what the schema provides, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches DNS Forwarder host overrides with filtering and pagination. It uses a specific verb and resource, distinguishing it from related tools like search_dns_host_overrides, but does not explicitly differentiate from that sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as search_dns_host_overrides or other search tools. The description only states the action without context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context (e.g., performance, rate limits, or return format), but does not contradict annotations. The mention of pagination is somewhat redundant given the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the primary action ('Search firewall rules') and briefly mentions key features. There is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema is rich with 9 well-described parameters, and an output schema exists, so the description needn't explain return values. Annotations cover safety. The description is minimal but adequate for a straightforward search tool, though it could benefit from usage guidance (already penalized in that dimension).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 nine parameters with descriptions. The tool description adds no additional meaning beyond the schema, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Search') and resource ('firewall rules'), and mentions 'advanced filtering and pagination.' While it doesn't explicitly distinguish from sibling tools like get_pf_rules or find_blocked_rules, the name and description convey a focused search capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_pf_rules, find_blocked_rules, or search_firewall_schedules. It does not state any exclusions or specific use cases, leaving the agent to infer from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds that filtering and pagination are supported, but doesn't disclose any additional behavioral traits such as default sorting or result limits, which are already in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. No redundant information is included, and it earns its place without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple search functionality, the presence of annotations, a complete parameter schema with descriptions, and an output schema, the description is mostly sufficient. It could be improved by mentioning that search_term filters by name/description, but that is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a clear description. The general mention of 'filtering and pagination' in the description echoes the schema but doesn't add new meaning beyond what the parameter descriptions already provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as searching firewall schedules, with filtering and pagination mentioned. It distinguishes from other search tools by the resource type, though it doesn't explicitly contrast with search_schedule_time_ranges or other schedule-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like search_schedule_time_ranges or create_firewall_schedule. It implies usage for searching schedules but offers no exclusions or preferred scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions 'filtering and pagination', which adds behavioral context beyond the readOnlyHint and destructiveHint annotations. However, it doesn't disclose return format, default sorting, or the client-side nature of filtering, leaving some behavioral aspects undocumented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core action and key features without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool with a complete output schema and fully documented parameters, the description is sufficient. It could be enhanced by naming searchable fields, but the schema already covers that. The combination of annotations, schema, and description provides adequate context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all four parameters fully described. The description's mention of 'filtering and pagination' vaguely maps to search_term and page/page_size, but adds no additional meaning beyond what the schema already provides. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'HAProxy frontends', making the tool's purpose unambiguous. It distinguishes from sibling search tools by naming the frontend resource specifically, though it doesn't explicitly contrast with search_haproxy_backends or frontend_addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. Sibling tools like search_haproxy_backends or search_haproxy_frontend_addresses are not mentioned, and there is no context about when this search is appropriate or how it differs from other search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent is aware this is a safe read operation. The description adds 'filtering and pagination,' which restates schema capabilities rather than providing new behavioral context like result limits or client-side 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of seven words, front-loaded with the action and resource. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity with a rich schema (100% coverage), solid read-only annotations, and an output schema present. The description is adequate for this context, but the unresolved ambiguity between `search_interface_configs` and `search_interfaces` prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (page, sort_by, page_size, search_term) already well-documented. The description's mention of 'filtering and pagination' maps to the schema but adds no meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and the resource ('interface configurations'), and mentions the key features of filtering and pagination. However, it does not differentiate from closely related siblings such as `search_interfaces` and `find_interfaces_by_status`, which could lead to confusion about which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, and does not mention any exclusions or prerequisites. Given the abundance of similar search tools in the sibling list, this lack of differentiation is a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds pagination behavior but does not disclose details like whether all NTP servers are returned, default sort order (though that is in the schema), or any special response handling. It adds some value but not rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: 'Search NTP time servers with pagination' — a single sentence that is front-loaded with the action and resource, and wastes no words. It is appropriately sized for a simple search tool with fully documented parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool has only three optional, self-explanatory parameters, the description is largely sufficient. However, it could benefit from mentioning that it lists all NTP time servers (since there are no filter parameters besides pagination) and that it complements 'manage_ntp_time_server' for lookups before edits. Still, for a simple paginated list, the current description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% since all three parameters have descriptions in the input schema. The tool's description does not add any parameter-specific information beyond what the schema provides, but it reinforces that pagination is a feature via 'with pagination'. Baseline 3 is appropriate because the schema carries the explanatory burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches NTP time servers and includes pagination, which is a specific verb+resource+scope. It distinguishes from 'manage_ntp_time_server' (which implies create/update/delete) and 'get_ntp_settings' (which likely retrieves configuration), though it doesn't explicitly address these sibling relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention that this is for listing/looking up NTP servers before modifying them via 'manage_ntp_time_server', nor does it note any exclusions or prerequisites. The sibling tool names imply context but the description itself provides no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the 'active' filter scope but does not disclose behavior like pagination defaults or filtering semantics; acceptable given annotations, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action ('Search') and the resource ('active OpenVPN server connections'). No filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only annotation, full schema parameter descriptions, and an existing output schema, the description does not need to explain return values or parameter details. It adequately positions the tool's purpose, though it lacks usage guidance, which is already scored separately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 4 parameters (page, sort_by, page_size, server_id) with types and defaults, so the description does not need to repeat them. The description adds no extra meaning beyond the schema, but the baseline is 3 due to the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'search' and identifies the resource 'active OpenVPN server connections', making its core function clear. It is distinguishable from sibling tools like get_openvpn_server_status by focusing on connection records rather than overall status, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_openvpn_server_status or get_openvpn_status. The description implies a search use case but does not state exclusions, alternatives, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context beyond what the schema provides, such as filtering behavior or pagination details, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and to the point, with no unnecessary words or repetition. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool with full schema coverage and an output schema present, the description is sufficient. It covers the core action and options, though it could potentially mention what types of tables are included, but this is not essential given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all four parameters. The description's mention of 'filtering and pagination' aligns with the parameters but adds no extra meaning beyond the schema, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches pf firewall tables with filtering and pagination, using a specific verb and resource. It distinguishes from get_pf_table by plural 'tables' and search semantics, though it doesn't explicitly contrast with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like get_pf_table or search_aliases. The description only implies usage through the verb 'search' and does not mention any exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows safety. However, the description does not disclose behavior such as whether results are paginated, whether all services are returned when no filters are given, or how status filtering is applied. It merely restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the key action and resource. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a high-fidelity schema, read-only annotations, and an output schema, the description is mostly complete for a simple search tool. However, it does not explicitly mention that no parameters are required (all optional with defaults), which might be useful context. Overall it is adequate given the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters have clear descriptions in the schema. The description 'Search and filter system services' adds no additional parameter semantics. Baseline 3 is appropriate since the schema carries the parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search and filter system services' — a specific verb and resource. It distinguishes itself from sibling tools like get_gateway_status or search_crls by explicitly targeting system services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. There is no mention of when to use this tool versus alternatives like 'system_status' or 'diagnose_service_health', nor any exclusion criteria. The one-line description leaves the agent to infer usage 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the behavioral detail of filtering and pagination, which helps set expectations for the result set, but otherwise provides no additional side-effect or authentication context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single, front-loaded sentence that immediately states the tool's purpose and key behaviors. It contains no filler or redundant restatement of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with an output schema, annotations, and fully-documented parameters, the description covers the core purpose and high-level behavior. The main missing piece is usage guidance against alternatives, but given the supporting structured data, the description is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all four parameters (page, sort_by, page_size, search_term). The description's mention of 'filtering and pagination' loosely corresponds to these parameters but adds no semantic details beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Search traffic limiters' with the clarifying parenthetical '(dummynet pipes)' to specify the exact resource, and mentions filtering and pagination. The verb+resource combination is specific and distinguishes this from sibling tools like search_traffic_shapers, though an explicit contrast with alternatives is absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this search tool versus sibling tools like search_traffic_shapers or the CRUD limiter tools. The description only states the action without any exclusion criteria or alternative recommendations, leaving it to the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the tool's mutating (but non-destructive) nature is clear. The description adds the fact that it sends a 'magic packet' (a specific WoL protocol), which is slightly informative. However, it does not disclose any additional behavioral traits such as network scope or lack of confirmation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the essential action without any unnecessary words. It is appropriately sized for a tool of this simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, two required parameters, 100% schema coverage, and presence of an output schema, the description is adequate. It fully states what the tool does, and no further context seems necessary for a straightforward WoL send operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for both parameters (mac and interface), so the schema fully explains their meaning. The description itself adds no parameter-level details, which is acceptable since the schema already covers them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Send a Wake-on-LAN magic packet' with a specific verb and resource. It is unambiguous and the scope is implied by the MAC address parameter. However, it does not explicitly differentiate from sibling tools, though no sibling appears to share this function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool or when to prefer an alternative. There is no mention of prerequisites, typical scenarios, or exclusions, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already signal a safe read-only operation (readOnlyHint=true, destructiveHint=false). The phrase 'feature validation' adds some behavioral context beyond the annotations, but it is too vague to fully disclose the tool's behavior, such as what specific features are validated or any network interactions involved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, begins with the action verb 'Test', and contains no redundant or filler content. It is appropriately sized for a simple zero-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is minimally adequate. However, it lacks clarity on what 'enhanced' and 'feature validation' entail, and does not convey when this tool should be used relative to similar capabilities, making it incomplete for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema fully covers parameter semantics. Per the baseline for zero parameters, this dimension scores 4. The description adds no parameter-specific information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a test operation for an 'enhanced API connection' with feature validation, giving a specific verb and resource. However, 'enhanced' and 'feature validation' are vague, and it does not differentiate from similar tools like get_api_capabilities or diagnose_connectivity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool, what prerequisites exist, or how it compares to alternatives. It only states what the tool does, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and idempotentHint=true, so the agent knows it's a safe mutation. The description adds only the 'existing' constraint and ID-based targeting, but does not disclose whether omitted fields are left unchanged or set to null, nor whether changes require apply_dns_forwarder_changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence, front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations cover safety and parameter documentation, but the description leaves critical update semantics unaddressed, such as partial vs full replacement behavior and the effect of apply_immediately. This is inadequate for a mutation tool despite the supporting resources.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all six parameters, so the baseline is 3. The description adds no parameter semantics beyond reinforcing the override_id requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('DNS Forwarder host override'), and the method ('by ID'). This distinguishes it from create, delete, and search siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing override but does not explicitly contrast with create/delete/search alternatives. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description simply restates the action 'Update' without adding behavioral context beyond what the annotations already provide. Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, but the description does not explain idempotency, the effect of null fields, or whether changes are immediately applied. It adds no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence: 'Update an existing DNS host override by ID'. It contains no redundant wording and is front-loaded with the action verb. Appropriate size for a tool whose schema and annotations already carry detailed information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having annotations and an output schema, the description fails to clarify important update semantics. Specifically, it does not state whether null parameter values mean 'leave unchanged' or 'clear the field', nor does it warn that setting apply_immediately=false requires a separate apply step. This ambiguity could lead the agent to accidentally clear fields or forget to apply changes. The schema descriptions do not resolve the null behavior, leaving a significant completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for 100% of parameters, including clear semantics like 'New list of IP addresses' and 'Whether to apply changes immediately'. The description adds no parameter-specific information, so it neither helps nor hurts. 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing DNS host override by ID' uses a specific verb (update) plus the exact resource (DNS host override) and the method (by ID). This clearly distinguishes it from create and delete siblings, and also from the DNS forwarder host override update tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing record (the word 'existing') but does not explicitly state when to use this tool vs alternatives like create or delete, nor does it mention the need to first search for the override_id. The schema's override_id description hints at search_dns_host_overrides, but the description itself lacks this context. Usage is implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=true, and destructive=false. The description adds no additional behavioral context, such as whether changes apply immediately (despite the apply_immediately parameter), whether a separate apply_nat_onetoone_changes call is needed, or any side effects. It does not contradict annotations but provides no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (10 words) that is front-loaded with the action and resource. It contains no fluff or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of NAT configuration and the existence of a sibling apply_nat_onetoone_changes tool, the description omits important operational context, such as how the update relates to applying changes and whether apply_immediately affects behavior. The tool has 9 parameters, but the description is too minimal to guide an agent on update semantics or follow-up actions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description does not add any meaning beyond the schema; it merely restates that the update is by ID, which is already clear from the 'mapping_id' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('1:1 NAT mapping'), and the identifier ('by ID'). It distinguishes this tool from siblings like create_nat_onetoone_mapping, delete_nat_onetoone_mapping, and search_nat_onetoone_mappings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing mapping, but does not explicitly mention when to prefer this over create or delete, or how to obtain the mapping ID (beyond the schema's parameter description). The usage context is only inferred from the verb 'update' and the word 'existing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) but it is idempotent and non-destructive. The description adds no behavioral context beyond the annotations, such as whether only provided fields are updated, whether changes require an apply step, or what happens on retries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that front-loads the action and resource. Every word contributes and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter update tool, the description does not explain that only supplied fields are modified, or that changes may need to be applied via apply_nat_changes. The output schema exists, so return values are covered, but important operational context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 14 parameters have schema descriptions with 100% coverage, so the schema carries most of the semantic load. The description only reinforces that mapping_id selects the target, adding no extra value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('an existing outbound NAT mapping'), and the selection criterion ('by ID'). This distinguishes it from sibling tools like create_nat_outbound_mapping and delete_nat_outbound_mapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by ID' implies the mapping must already exist and be identified via a search operation. However, there is no explicit guidance on when to use this tool vs alternatives, nor any mention of needing to call apply_nat_changes after updates to make them effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds no additional behavioral context, such as partial-update semantics (null fields unchanged) or whether apply_immediately controls live application. With annotations covering the core behavior, a score of 3 is appropriate; the description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource, and contains no filler. It is appropriately sized for the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema and annotations, this is a complex mutation tool with 26 parameters. The description does not explain key behavioral expectations such as optional fields being ignored when null, the role of apply_immediately, or the effect of idempotency. It leaves the agent to infer usage from the schema alone, which is insufficient for correct invocation in non-trivial scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 every parameter meaning. The description adds nothing beyond that. For each optional parameter, the schema gives a terse description, but the description does not clarify that null means 'leave unchanged'—this is an important nuance not covered. Baseline 3 is maintained because structured fields do the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing OpenVPN server instance by ID' uses a specific verb ('Update') with a clear resource ('OpenVPN server instance') and a scoping constraint ('by ID'). It clearly distinguishes this tool from siblings like create_openvpn_server, delete_openvpn_server, and search_openvpn_servers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for modifying existing servers (as opposed to creating or deleting), nor does it explain prerequisites like needing to obtain the server_id via search_openvpn_servers. The schema mentions where server_id comes from, but the description itself offers no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the basic creation operation. Annotations already indicate it is not read-only and not destructive, but the description does not disclose side effects (e.g., whether changes require an apply, authentication/authorization needs, or whether it can overwrite existing servers).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler words. It immediately communicates the tool's purpose and the supported types, making it efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 18 parameters, the description is minimal. It does not explain that different parameters apply depending on the 'type' field (LDAP vs. RADIUS), though the schema's per-parameter descriptions partially compensate. Without this guidance, an agent may struggle to choose the correct required fields for a particular type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter individually documented (e.g., port defaults, LDAP/RADIUS specific fields). The description adds no extra parameter meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('authentication server'), and specifies the two supported types (LDAP or RADIUS), which unambiguously distinguishes it from sibling tools like update_auth_server or delete_auth_server.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Create' and resource name imply this is for creating new auth servers, but there is no explicit guidance on when to choose this over update_auth_server or delete_auth_server, nor mention of any prerequisites or post-creation steps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as non-read-only and non-destructive, but the description adds no behavioral context beyond the word "Create." It does not disclose effects like immediate application, relationship to the DNS resolver configuration, or any side effects of creating an entry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and target. It contains no filler, repetition, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage and an output schema present, the description does not need to explain return values or parameter formats. However, it omits operational context such as the role of apply_immediately or how this interacts with apply_dns_resolver_changes, making it only minimally complete for real-world use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 parameters including aclname, aclaction, networks, descr, and apply_immediately. The description itself adds no parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb "Create" and identifies the exact resource "DNS Resolver access list entry," which clearly distinguishes this from sibling update/delete/search_dns_access_lists operations. It conveys the unit of work (an entry) rather than just the broad resource category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the verb "Create" and the resource name; there is no explicit statement of when to use this tool versus alternatives such as update_dns_access_list or delete_dns_access_list. It also does not mention any prerequisites or whether apply_dns_resolver_changes is needed afterwards.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The WARNING that 'This modifies the running firewall configuration' adds behavioral context beyond the readOnlyHint=false annotation, alerting the agent to mutation of a live system. However, it doesn't disclose potential traffic disruption, the default of apply_immediately=true, or other side effects that could affect network connectivity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: a clear purpose statement and a necessary warning. No filler or redundant information. The structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 15-parameter mutation tool, the description is minimal. It lacks preconditions, side effects, or relationship to apply_firewall_changes. However, the rich schema and output schema compensate significantly, leaving only moderate gaps in high-level context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 15 parameters with formats, defaults, and semantic notes (e.g., position rule created first then moved). The description adds no parameter-specific meaning, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a firewall rule on the live pfSense appliance', using a specific verb and resource. It naturally distinguishes from sibling tools like update_firewall_rule, delete_firewall_rule, and move_firewall_rule. Although the 'advanced' suffix isn't explained, 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like update_firewall_rule or move_firewall_rule. It doesn't mention prerequisites, when not to use it, or how it relates to apply_firewall_changes. The warning implies caution but does not direct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, which are consistent with a create operation. However, the description adds no behavioral context beyond the annotations, such as the effect of apply_immediately or whether changes are staged. This leaves the agent without crucial execution details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's purpose without any redundancy. It is appropriately sized and front-loaded, wasting no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are covered. However, the tool has 5 parameters and a notable apply_immediately flag, yet the description gives no context about the apply workflow or any side effects. This is adequate but leaves clear gaps for a create tool in a larger configuration management system.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% descriptions for all 5 parameters, including username, password, ip, descr, and apply_immediately. The description adds no additional parameter semantics, so it meets the baseline for high schema coverage without further contribution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'FreeRADIUS user'. It distinguishes from sibling tools like update_freeradius_user, delete_freeradius_user, and search_freeradius_users by conveying a specific create operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding a new FreeRADIUS user but does not explicitly mention alternatives or exclusions. No reference to when to use create versus update/delete/search, and no prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation, and the description's 'Create' is consistent. The phrase 'within a firewall schedule' adds useful scoping context beyond the annotations, clarifying that this is a nested resource creation. However, no additional behavioral details are provided (e.g., immediate application, side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundancy. It is front-loaded with the action and resource, making it easily scannable and appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the detailed schema (100% coverage), output schema presence, and annotations, the description is minimally viable. However, it lacks usage guidelines and behavioral context such as the need for an existing parent schedule or the impact of apply_immediately, leaving some gaps for a 7-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all seven parameters individually described (e.g., hour format '8:00-17:00', position weekday mapping). The description itself adds no parameter-specific meaning, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the specific resource ('a time range within a firewall schedule'). This distinguishes it from sibling tools like create_firewall_schedule (which creates the whole schedule) and update/delete_schedule_time_range, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., parent schedule must exist), and no exclusions. The agent must infer usage context entirely from the schema and sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but non-destructive operation. The description adds no behavioral context beyond 'create', such as persistence across reboots, duplicate handling, or side effects of apply_immediately. This leaves important behavioral traits undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the core purpose and includes a useful parenthetical clarification, all in nine words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema and output schema, the description covers basic purpose but omits critical context like handling existing tunables, prerequisites, or whether apply_immediately has side effects. The sibling tools imply a lifecycle, but the description alone is not fully complete for safe and correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 four parameters (descr, value, tunable, apply_immediately). The description adds minimal extra meaning beyond the 'sysctl value' clarification, which does not substantially enhance understanding of individual parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('system tunable') with a clarifying parenthetical ('sysctl value'). It clearly distinguishes from sibling tools like search_system_tunables, update_system_tunable, and delete_system_tunable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, such as using update_system_tunable for existing tunables or search_system_tunables for lookup. Usage is implied by the tool name and sibling context, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds 'irreversible' which strengthens the warning. However, it fails to mention the confirm flag requirement or dry_run preview capability, both crucial for safe execution of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence plus warning. Every word contributes to purpose or risk communication; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 4 params, output schema, and destructive annotations. Description is minimally adequate but omits critical operational context like the need to set confirm=True or use dry_run. Schema covers param semantics, but the description should bridge why those safety gates exist and how they interact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with clear descriptions, including user_id origin and confirm as a safety gate. The description's 'by ID' adds nothing beyond the schema's user_id description, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Delete' with resource 'FreeRADIUS user' and scope 'by ID', clearly distinguishing it from sibling delete_freeradius_client and other delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor mention of prerequisites like obtaining the user ID via search_freeradius_users. The irreversible warning implies caution but does not provide explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the qualifier 'current', indicating it returns the live settings rather than defaults, but provides no additional behavioral context such as auth needs or output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. It is appropriately sized with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with a defined output schema and safety annotations, the one-line description is sufficient. It doesn't cover edge cases like package absence, but the output schema handles return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100% trivially. With zero parameters, the baseline is 4 and the description need not explain parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'Get' and the specific resource 'ACME package settings', making the tool's purpose evident. It distinguishes from sibling get_* settings tools by naming the ACME package, but is otherwise terse and doesn't add further differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternative settings getters, nor any mention of prerequisites or context. The description simply states what it does, leaving usage entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context by warning about a known upstream failure (server-side OOM on large logs) and providing a fallback. This goes beyond the structured annotations to disclose reliability caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with the purpose front-loaded and a necessary warning. The warning is slightly verbose but each sentence serves a purpose; no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with full schema parameter descriptions and an output schema, the description adequately covers the main caveat (potential failure on large logs). It does not explain return format or pagination, but those are likely covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all 7 parameters individually described, so the schema carries the parameter semantics. The description's 'optional filtering' adds no new information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get firewall log entries with optional filtering' – a specific verb and resource that clearly identifies the tool's function. It does not explicitly contrast with related sibling tools like search_logs_by_ip or analyze_blocked_traffic, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The warning only suggests SSH/web UI as a fallback after failure, not as a primary usage guideline, and no sibling tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the tool can 'remove' domain entries, which is destructive, but the annotations declare destructiveHint=false. This is a direct contradiction. The schema further reinforces the destructive nature by requiring a confirm flag for delete operations, making the annotation inconsistency severe.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the purpose in the first sentence. The second paragraph adds valuable context about ACME validation and alternatives without redundancy. It earns its length, though slightly verbose with the background explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given high schema coverage, an output schema, and the presence of sibling tools, the description provides sufficient context by explaining per-entry behavior and contrasting with update_acme_certificate. It doesn't explain return values, but that is not required when an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 8 parameters, so the description carries little additional parameter-level meaning. It does add high-level context about validation methods, but the schema already handles parameter semantics thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Add or remove a domain (SAN) validation entry on an ACME certificate.' It clearly distinguishes itself from update_acme_certificate by noting that it manages entries one at a time rather than replacing the entire a_domainlist array, making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when ACME domain entries are needed and explicitly contrasts this tool with update_acme_certificate for full-replace operations. It implies the appropriate use case for per-domain management, though it doesn't enumerate explicit 'when not to use' scenarios beyond the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds minimal context beyond the annotations, only specifying that the search is scoped to CAs configured on pfSense. It does not disclose pagination behavior or return format, but the output schema likely covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's purpose without any redundant wording. It is concise and front-loaded, earning a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with optional parameters and an output schema, but the description lacks usage guidance and does not explain how search_term matches against CA fields. It is minimally viable but leaves the agent to infer when to use it versus related certificate tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all three parameters (page, page_size, search_term). The description itself provides no additional parameter semantics, but the baseline of 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Certificate Authorities (CAs) configured on pfSense. It uses a specific verb 'Search' and a specific resource, distinguishing it from sibling tools like search_certificates, which searches certificates rather than CAs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no exclusions, and no mention of related tools like search_certificates or create_certificate_authority. It simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Search' action aligns with this. However, the description adds minimal behavioral context beyond the annotations, such as pagination default or filtering capabilities, which are already apparent from the schema. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately conveys the purpose without unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters but all are optional with defaults, and the schema and annotations cover most aspects. However, the description lacks any mention of relationship to sibling DHCP tools or pagination behavior, making it minimally viable but not wholly comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description itself adds no parameter-specific semantics; the filter parameters are well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: searching DHCP static mappings (reservations) with filtering. It distinguishes from sibling tools like search_dhcp_leases by specifying the resource (static mappings) and adds a clarifying synonym (reservations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_dhcp_leases. It only describes the operation itself, leaving the agent to infer applicability without explicit comparisons or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds only 'filtering and pagination', which is already evident from the schema and tool name. It does not disclose additional behavioral traits such as access requirements, rate limits, or the nature of results beyond what annotations (readOnlyHint, destructiveHint) already communicate. No contradiction exists, but the value added beyond annotations is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the verb and resource. Every word earns its place, and there is no redundant or verbose content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool, the presence of a full output schema, and complete annotation coverage, the description is adequate but minimal. It does not explain what an encryption entry is or how this search relates to parent Phase 2 objects, which could aid selection among many similar search tools. The lack of context about the parent_id filter creates a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add any parameter-specific details beyond what the schema already provides; it merely repeats the concept of filtering and pagination. Thus, the schema carries the semantic load, and the description adds no meaningful enhancement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and identifies the resource as 'IPsec Phase 2 encryption entries', distinguishing it from related sibling tools like search_ipsec_phase1_encryptions, search_ipsec_phase2s, and CRUD operations. It clearly states what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'with filtering and pagination', but it does not explicitly state when to use this tool over alternatives or provide any exclusions. No alternative tools are mentioned, leaving the agent to infer from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, establishing the safety profile. The description adds no behavioral context beyond the action itself, such as whether changes require separate application (despite the apply_immediately parameter) or how partial updates are handled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence—'Update an existing BIND DNS zone by ID'—that is front-loaded and free of any filler. It is appropriately sized for the simplicity of the operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations provide rich structured context, but the description lacks guidance on usage boundaries and does not clarify partial update semantics or the role of apply_immediately. It is minimally adequate for selecting the tool, but the agent must infer important behavioral details not supplied by the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are fully documented in the schema with descriptions, giving 100% coverage. The tool description itself adds no extra parameter semantics, so it correctly relies on the schema for meaning, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' with the resource 'existing BIND DNS zone' and specifies 'by ID', clearly distinguishing it from create_bind_zone, delete_bind_zone, and other BIND management tools. It directly and unambiguously states what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing zone by ID, but it provides no explicit guidance on when to use this tool versus create_bind_zone or delete_bind_zone, nor does it mention any prerequisites or alternative tools. The context is sufficient for basic selection but lacks clear exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The parenthetical '(idempotent)' merely echoes the existing idempotentHint=true annotation, adding no new behavioral context. The description does not disclose whether changes require an apply step, prerequisites, or any side effects, relying entirely on annotations that are already present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is eight words in a single sentence, front-loaded with the verb and resource. Every word earns its place, with no filler or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage, useful annotations, and presence of an output schema, the description is minimally adequate. However, it does not address the meaningful distinction from related tools like renew_certificate or generate_certificate, leaving a clarity gap in tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for all four parameters (PEM private key, certificate data, descriptive name, and ID source). The description itself adds no parameter-level detail 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') with a clear resource ('certificate') and targeting mechanism ('by ID'). It distinguishes from sibling tools like create_certificate, delete_certificate, generate_certificate, and renew_certificate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for existing certificates (vs creating new ones) but provides no explicit when-to-use/when-not-to-use guidance. It does not mention alternatives such as renew_certificate or generate_certificate, nor does it advise searching first, though the schema hints at this via the certificate_id description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so no contradiction. The description adds the backend-switching scope but does not disclose potential side effects such as service restarts or lease impact, which would be valuable beyond the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 9-word sentence, front-loaded with the verb and resource, and contains no filler or redundant information. It is appropriately concise for the simple scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple two-parameter schema, output schema, and safe annotations, the description covers the core action. However, it lacks context on operational impact (e.g., brief DHCP interruption, whether changes require a follow-up apply) which could be important for an agent deciding to invoke the tool. It is adequate but not enriched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are well documented. The description's parenthetical ('ISC DHCP vs Kea') essentially repeats the schema's dhcpbackend enum values without adding new semantic information, so it does not enhance the parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('DHCP server backend') and clearly scopes the action to the two backend options ('ISC DHCP vs Kea'). This distinguishes it from sibling tools like update_dhcp_server_config or apply_dhcp_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_dhcp_server_config or apply_dhcp_changes. It does not mention prerequisites, consequences, or explicit exclusions, leaving the agent to infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive, idempotent operation, but the description adds no behavioral context about partial-update semantics. It fails to clarify whether omitted optional parameters are left unchanged or reset to null, and it doesn't explain the impact of apply_immediately=false. This could lead the agent to unintentionally clear fields or miss a required apply step.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no redundant information. It immediately states the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although the schema and output schema cover mechanics, the description is missing critical context about update semantics (partial vs full update) and the apply_immediately behavior. Without this, an agent might not know how to correctly set optional fields or when to call apply_dhcp_changes. The description is minimally viable but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with all seven parameters described, so the description adds no parameter-level value. The baseline 3 is appropriate; there is no missing information that the description needs to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('DHCP static mapping'), and the scope ('by ID'), which distinguishes it from create, delete, and search siblings. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the CRUD pattern: update an existing mapping by ID. However, the description does not explicitly mention when to use this tool versus create or delete, nor does it advise finding the mapping ID via search. This is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description adds no extra behavioral context. It only repeats 'existing' and 'by ID', which are already in the schema, without disclosing side effects or retry implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It earns its place and is front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, the presence of an output schema, and the detailed input schema, the description provides the minimum viable context. However, it omits guidance on the apply_immediately parameter's practical effect (e.g., staging changes vs. applying now), which could be important for an agent deciding on multiple updates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description itself does not elaborate on parameter semantics beyond the schema, but the schema already contains meaningful descriptions for all six parameters, including user_id referencing search_freeradius_users.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Update), the resource (existing FreeRADIUS user), and the method of identification (by ID). It naturally distinguishes from sibling tools like create_freeradius_user and delete_freeradius_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing user, but it does not explicitly mention alternatives or exclusions (e.g., 'use create_freeradius_user for new users'). The context is clear but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, idempotent, non-destructive operation. The description adds little beyond the annotations, saying only 'update' without disclosing side effects, error conditions, or whether changes are applied immediately. It is consistent with the annotations, so no contradiction, but it adds minimal extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no redundant words. It is front-loaded with the verb and resource, making it immediately clear what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, an output schema, and annotations, the description is minimally sufficient but has clear gaps. It does not mention the apply_immediately parameter's role or the existence of apply_routing_changes, which is a sibling tool. The description also omits guidance on obtaining the gateway_id via search_gateways. While the schema fills in parameter details, the overall workflow context is thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all 10 parameters, so the baseline is 3. The description itself does not add any additional parameter semantics beyond what the schema already states, nor does it need to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing routing gateway by ID' clearly specifies the action (update), the resource (routing gateway), and the identification method (by ID). It effectively distinguishes this from sibling tools like create_gateway, delete_gateway, and update_default_gateway by emphasizing 'existing' and 'by ID'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., obtaining the gateway ID via search_gateways) or the relationship to apply_routing_changes. The use case is only implied by the word 'existing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds one behavioral trait: the pfSense API rejects a certificate with no domains, so at least one domain/SAN must be provided. This is useful context beyond the annotations, but it is minimal. The description does not disclose other potential side effects (e.g., whether it triggers any background process) or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first clearly states the purpose, the second provides a critical caveat about the domain requirement. No unnecessary words or repetition. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich input schema (100% coverage) and an output schema, so the description need not explain parameters or return values. The description adequately covers the most important non-schema context (API rejection of empty domain list). However, it could be slightly more complete by clarifying that this creates only an ACME certificate entry and that actual issuance is handled by a separate tool (issue_acme_certificate).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides comprehensive descriptions for all 7 parameters (100% coverage), including detailed guidance on a_domainlist formatting and dnssleep behavior. The description itself adds no new parameter semantics beyond restating that a_domainlist is required. Per the rubric, with full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create an ACME certificate entry') with a specific resource (ACME certificate). The verb 'create' distinguishes it from sibling tools like update, delete, issue, and renew. No ambiguity about the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that this creates only an entry and that issuance/renewal are separate steps (issue_acme_certificate, renew_acme_certificate). The note about the domain requirement is a constraint, not usage guidance. This is a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a write operation. The description adds useful context about routing to different API endpoints and conditionally required fields, which is valuable, but it does not go into deeper behavior like response details or side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the first sentence giving a clear, front-loaded purpose and the second providing a concise note on routing behavior. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 16 parameters and an output schema, the description covers the core routing behavior but omits guidance on choosing between this and sibling tools like generate_certificate. It also does not mention prerequisites such as an existing CA for internal generation, leaving some gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 16 parameters, providing clear meaning for each field. The description adds extra context by noting that required fields differ between import and internal generation, helping to explain why certain parameters become necessary based on 'method'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create or import) and the resource (certificate on pfSense), specifying the object and operation. It covers both import and internal generation, which helps distinguish it from siblings like generate_certificate, though it does not explicitly name alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that import and internal generation use different endpoints and required fields, and that routing depends on the 'method' parameter. This gives some context for when to use which method, but it does not explicitly state when to prefer this over generate_certificate or other certificate creation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation, but the description adds no additional behavioral context such as permissions requirements, failure conditions, or idempotency. It simply restates the action without revealing any constraints or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action and resource, containing zero filler words. It effectively communicates the purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple create operation, the detailed schema, and the presence of an output schema, the description is sufficient for an agent to understand the tool's basic purpose. However, it lacks any additional operational context such as uniqueness constraints, prerequisites, or post-creation steps, which would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all five parameters, and the description itself offers no extra parameter-level context. Since schema coverage is high, the baseline score of 3 is appropriate, and there is no additional semantics provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' and identifies the resource as 'a new pfSense user group,' clearly distinguishing it from sibling tools that update, delete, or search groups. It is unambiguous and directly states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as search_groups, update_group, or delete_group. Usage is implied by the name and purpose, but there are no context cues, prerequisites, or exclusion statements to help the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds no additional behavioral context (e.g., duplicate handling or side effects), but it does not contradict the annotations either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the action verb. It contains no wasted words and 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's straightforward purpose, the comprehensive parameter schema, and the presence of an output schema, the description is mostly complete. It could mention potential side effects, but the core action is clearly communicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all 8 parameters have their own descriptions in the schema. The tool description itself adds no parameter-specific 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and identifies the resource as 'pfSense local user', which clearly distinguishes it from sibling tools like create_group or create_firewall_rule. It is immediately clear what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_user or delete_user. It only states the action without contextual hints or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds no behavioral detail beyond the action itself; it does not mention side effects, immediate application behavior, or the need for a parent tunnel.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is efficient and immediately conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a moderately complex schema (9 parameters) but all parameters are well-documented, annotations cover the safety profile, and an output schema exists. The description clearly states the core operation; the schema handles details like apply_immediately behavior. A complete description for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter is thoroughly described (e.g., the 'enabled' parameter notes that upstream defaults to disabled). The description adds no additional parameter semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and clearly identifies the resource ('WireGuard peer') and scope ('on a tunnel'). It effectively distinguishes this tool from sibling tools like update_wireguard_peer, delete_wireguard_peer, and search_wireguard_peers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, but the verb 'Create' implies this is for new peer creation, and sibling names provide sufficient context. Lacks mention of prerequisites such as requiring an existing tunnel.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WARNING: This is irreversible,' going beyond the destructiveHint annotation by specifying permanence. This is useful behavioral context. However, it does not mention the confirm/dry_run safety gates, which are documented in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the action is front-loaded, and the warning is direct. There is no redundancy or unnecessary detail, making it efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that annotations cover destructiveness, the schema fully describes parameters (including the confirm gate), and an output schema exists, the description is sufficiently complete for a simple delete operation. It lacks explicit usage guidance but is otherwise adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the tool description adds no parameter-level meaning. The schema already provides informative descriptions, including the override_id source from search_dns_domain_overrides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and resource 'DNS domain override', making the operation clear. However, it does not explicitly contrast with other delete tools for different override types (e.g., host overrides), so it lacks direct sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, such as when to use delete_dns_host_override or how to obtain the override ID. It only states the action without context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'irreversible' warning adds a useful nuance beyond the structured metadata. However, it does not disclose other important behavioral aspects such as the requirement to set confirm=True or the impact on dependent routing rules, though those are indirectly captured in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, clearly stating the action and the critical warning. No filler or repetition; every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich annotations (destructiveHint), full schema coverage, and presence of an output schema, the description does not need to re-explain details. It adequately covers the high-level purpose and the key caveat of irreversibility. However, it omits explicit mention of the confirm and dry_run safety gates, which are available in the schema but would be valuable for an agent to consider before invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of the parameters, so the schema already explains each parameter (confirm, dry_run, gateway_id, apply_immediately). The description adds no additional parameter-level semantics beyond pointing to 'by ID', which is redundant with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Delete a routing gateway by ID') with a clear verb and resource. It distinguishes from siblings like delete_gateway_group by specifying 'routing gateway' and the target is a single gateway, not a group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites (e.g., looking up the gateway_id via search_gateways), or conditions that should be checked before deletion. The only hint is the irreversibility warning, which implies caution but does not explain how to proceed safely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false), idempotency (idempotentHint=true), and non-destructiveness (destructiveHint=false). The description adds no extra behavioral context beyond 'existing alias', which is already implied. It does not contradict annotations, so a neutral score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of nine words. It is front-loaded, contains no filler, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool, the description sufficiently covers the operation and target. The presence of an output schema reduces the need to explain return values. However, it could be more complete by noting when to prefer this over update_alias, but that is not essential for functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for all three parameters (alias_id, action, addresses). The description adds no additional parameter details, but the schema does the heavy lifting, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add or remove addresses from an existing alias' uses a specific verb phrase (add or remove) and names the resource (addresses on an alias). It clearly distinguishes from sibling tools like create_alias and delete_alias, and implies a sub-operation on an existing alias rather than general update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus update_alias, which could also modify alias properties. The description implies usage through the name but does not state exclusions or alternatives, so an agent may struggle to choose between them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as non-read-only and non-destructive; the description adds no behavioral context beyond the basic action. It does not mention side effects on other rules, whether changes require an explicit apply step, or what happens to rule ordering indices.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence that directly states the tool's function with no wasted words; front-loaded and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple reorder tool with complete parameter documentation and safety annotations, the description covers the core purpose. Minor gap: doesn't mention that changes may need to be applied or that rule position is zero-based (though schema covers this). Overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema provides detailed descriptions for all parameters (100% coverage), including rule_id as array index and new_position semantics. The description adds no parameter-level detail beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Move') with a clear resource ('firewall rule') and target ('new position in rule order'), distinguishing it from sibling tools like update_firewall_rule or delete_firewall_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reordering firewall rules, but it does not explicitly state when to use this over alternatives or mention prerequisites like needing to retrieve rule_id from search_firewall_rules (though schema does). No exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (`destructiveHint: true`) and not read-only (`readOnlyHint: false`). The description adds the consequence of 'service interruption,' which is a meaningful behavioral trait beyond the annotation. It does not mention other effects like session loss, but the warning is valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary action and a crucial warning. Every word earns its place; there is no filler. It is appropriately minimal for a simple operational tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive reboot tool with annotations and an output schema, the description is adequate but not exhaustive. It states the operation and consequence. However, it could be more complete by mentioning the sibling `halt_system` for context, and clarifying that `confirm` must be true to execute (though the schema covers that). Overall, the information is sufficient for a basic agent, but not as complete as a fully contextual description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers both parameters (`confirm` and `dry_run`) with descriptions, so the description adds no parameter-level meaning. With 100% schema coverage, the baseline of 3 applies. The description doesn't reference these parameters, but that's acceptable given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reboot') and the target ('the pfSense system'). However, it does not explicitly distinguish this tool from the sibling `halt_system` tool, which also affects the system's power state. The verb 'reboot' is specific enough to infer the operation, but a direct alternative mention is missing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives like `halt_system` or other restart procedures. The warning about service interruption is a caution, not a usage directive. There is no mention of prerequisites (e.g., setting `confirm=True`) or scenarios where 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and non-destructive. The description adds no behavioral context beyond this, such as pagination behavior, default sorting, or client-side filtering details. It merely restates the search function without disclosing additional traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the tool's purpose with no wasted words. It is appropriately concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (all parameters documented), read-only annotations, and presence of an output schema, the description is adequate for a simple search tool. However, it could be slightly more helpful by noting that search_term filters by command/who fields, though that information is already in the schema. Overall, the description plus structured data provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for parameters, providing details for page, sort_by, page_size, and search_term. The description's mention of 'filtering and pagination' loosely maps to these parameters but does not add meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search cron jobs with filtering and pagination' uses a specific verb and resource, clearly indicating the tool's function. It distinguishes itself from sibling tools like create_cron_job and delete_cron_job by focusing on searching, and the mention of filtering/pagination adds functional scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching cron jobs but does not explicitly state when to use it over alternatives or any exclusions. There is no mention of prerequisites or when to prefer other tools, leaving usage guidance to the user's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the behavior of filtering and pagination, but this is also evident from the input schema, providing minimal additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It contains no unnecessary words or repetition, making it efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with complete schema documentation and an output schema, the description adequately states the core function. It is not overly detailed, but the schema and annotations fill in the remaining context, making it sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented. The description only generically mentions 'filtering and pagination' and does not add any new meaning beyond what is already in the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'DNS domain overrides', distinguishing it from sibling tools like search_dns_host_overrides and search_dns_forwarder_host_overrides. It also mentions filtering and pagination, which precisely describes the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention conditions for using it, exclusions, or relationships to similar search tools. There is no 'when-to-use' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the prerequisite of HAProxy package installation, which is useful context beyond annotations. However, it does not disclose return behavior, pagination details, or any non-obvious side effects. The added context is minimal but relevant, and there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary action, followed by a single prerequisite. Two sentences carry all necessary information without any filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full input schema and an output schema present, the description does not need to explain return values. It covers the core functionality and a key prerequisite. It lacks explicit differentiation from sibling search tools, but the name and annotations cover much of the necessary context, making it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (page, sort_by, page_size, search_term) having a description in the schema. The tool description itself adds no additional parameter semantics beyond what the schema already 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search HAProxy backends with filtering and pagination', specifying the exact resource (HAProxy backends) and the operations (search with filters and pagination). This distinguishes it from sibling tools like search_haproxy_frontends and search_haproxy_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is the prerequisite that the HAProxy package must be installed on pfSense. There is no explicit guidance on when to choose this tool over alternatives, nor exclusions or comparisons to sibling search tools. The name itself provides implicit differentiation, but no direct guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond what the schema indicates (filtering and pagination), such as pagination behavior, result limits, or client-side filtering specifics. It provides zero new transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core purpose, and no wasted words. The name and description align perfectly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with full schema parameter descriptions and an output schema, the description is adequate. It states the resource and key capabilities. However, it could slightly improve by explicitly distinguishing from sibling NAT search tools, but this is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters have descriptions in the schema (100% coverage), so baseline is 3. The description's mention of 'filtering and pagination' adds no meaningful detail beyond schema descriptions; it only summarizes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' with the clear resource '1:1 NAT mappings' and mentions 'filtering and pagination'. It effectively distinguishes this tool from sibling NAT search tools like search_nat_port_forwards and search_nat_outbound_mappings by specifying the 'onetoone' resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding one-to-one NAT mappings but does not explicitly state when to use this tool over alternatives or provide exclusions. The sibling names offer differentiation, but the description itself lacks direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds 'filtering and pagination' as behavioral features, but does not explain response format or any rate limits. With annotations covering the safety aspects, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that captures the essence without redundancy. It is front-loaded with the action and resource, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations, 100% schema coverage, and output schema, the description covers the essential context. It lacks explicit guidance on edge cases or return value explanation, but the output schema presumably covers this, so completeness is strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 7 parameters are well-documented in the schema itself. The description's mention of 'filtering and pagination' aligns with the parameters but adds no extra semantic depth beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and identifies the resource ('NAT port forwarding rules'), making the core purpose clear. However, it doesn't explicitly distinguish this from sibling tools like search_nat_onetoone_mappings or search_nat_outbound_mappings, though the resource name itself provides some differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions filtering and pagination, which implies usage for querying NAT port forwarding rules with those capabilities. It doesn't explicitly state when to use this tool versus alternatives, but the resource name and context signals make the use case reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that it supports filtering and pagination, which is some behavioral detail, but it does not disclose result limits, default sorting, or other edge-case behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the core purpose and key capabilities. It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple search semantics, optional parameters, and presence of an output schema, the description is mostly sufficient. However, it does not clarify whether 'client instances' refers to configured clients or active sessions, and does not explain how it differs from other OpenVPN-related search tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly documented (e.g., protocol, interface, search_term). The description adds minimal value, only hinting at filtering and pagination, which are already evident from the parameter list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Search') and the resource ('OpenVPN client instances'), and mentions filtering and pagination. It distinguishes from sibling tools like search_openvpn_servers by explicitly targeting clients, and the name itself reinforces this distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as search_openvpn_servers, get_openvpn_client_status, or session-specific tools. The description simply states functionality without contextualizing its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no behavioral context beyond that, such as pagination behavior or filtering semantics, but it is consistent with the annotations and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. There is no redundancy, filler, or unnecessary detail, making it optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of a search tool, the presence of an output schema, and full parameter documentation, the description is sufficiently complete. It does not explicitly explain return values or filtering nuances, but these are covered by the schema and output schema, so the overall context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (page, sort_by, page_size, server_id) are fully documented in the schema. The description itself adds no parameter semantics, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and identifies the resource as 'OpenVPN server routing table entries', clearly distinguishing it from sibling tools like search_openvpn_server_connections or get_openvpn_server_status. It is not a tautology and precisely states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_openvpn_server_connections or get_openvpn_server_status. It lacks any context about preferred scenarios, exclusions, or comparisons with related search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'with pagination', which is a behavioral trait but it is also fully evident from the input schema's page and page_size parameters. No additional behavioral context (e.g., rate limits, authentication, or response format) is provided, but given the annotation coverage, the description adds minimal value beyond what is already known.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately provides the essential purpose. It uses no filler words and is front-loaded with the main action and resource, followed by the key detail about pagination. Perfectly structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple search tool, the description combined with the annotated read-only hint, fully documented input schema, and presence of an output schema provides sufficient context for an agent to invoke it correctly. A minor gap is that it does not explain what a 'service watchdog' is or explicitly state that it returns a list of watchdogs, but for a domain-aware agent this is unnecessary. The description is complete enough for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with descriptions for all three parameters (page, sort_by, page_size). The description does not add any additional meaning or context for these parameters, so the baseline of 3 is appropriate. It does not compensate with examples, allowed values, or relationships between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'service watchdogs', providing a specific and unambiguous purpose. It distinguishes from sibling tools like 'manage_service_watchdog' (which implies modification) and 'search_services' (different resource), making the tool's role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is a read-only list/search operation compared to 'manage_service_watchdog' which modifies watchdogs, nor does it state any preconditions or relationship to other search tools. The context is implied only by the sibling names, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context beyond the obvious 'update' operation—it doesn't discuss apply_immediately effects, DNSSLEEP implications, or what happens to existing values. Thus it provides minimal value beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence: 'Update an existing ACME certificate entry by ID'. Every word contributes to the core purpose, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (8 parameters, full descriptions), annotations, and output schema, the short description is adequate for locating the tool. It lacks any statement about what the update does with unspecified fields, but the schema's param details and annotations fill most gaps. Slightly more context about the tool's role in the ACME workflow would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema itself thoroughly documents parameters (e.g., a_domainlist explains replacement vs. single-domain management, dnssleep describes network blocking scenarios). The description adds no parameter information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing ACME certificate entry by ID' uses a specific verb ('Update'), names the resource ('ACME certificate entry'), and specifies the lookup mechanism ('by ID'). This clearly distinguishes it from related tools like create_acme_certificate, delete_acme_certificate, and even generic update_certificate by the 'ACME' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when updating an existing ACME certificate, but does not explicitly state when to use this tool over alternatives. For example, it doesn't mention that manage_acme_certificate_domain should be used for single-domain additions/removals, although that guidance appears in the schema's a_domainlist parameter description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context ('existing' and 'by ID') but doesn't contradict annotations. It doesn't reveal side effects like config reload behavior, but the apply_immediately parameter in schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It efficiently communicates the core functionality without any waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being brief, the description is supported by a rich schema, comprehensive annotations, and an output schema. The only significant gap is usage guidance, which is already scored separately. For a tool of this complexity, the overall package is nearly complete, though the description could have mentioned partial-update semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly documented including defaults and nested structures for bind_addresses. The description itself adds no extra parameter meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Update'), resource ('HAProxy frontend'), and scope ('by ID'). It effectively distinguishes this tool from siblings like create_haproxy_frontend and delete_haproxy_frontend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites like obtaining frontend_id via search_haproxy_frontends, nor does it explain when to choose update over create/delete. The schema hints at the ID source, but the description itself offers no context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, non-destructive, and idempotent operation. The description adds no further behavioral context, such as whether unspecified parameters are left unchanged or set to null. This is a critical gap for an update tool with many optional fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('Update') and the object ('IPsec Phase 1 (IKE) entry'). Every word earns its place, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 15 parameters and complex partial-update semantics, the description is far too terse. It does not explain the behavior of null fields, the role of apply_immediately, or the relationship to apply_ipsec_changes. Even with an output schema, these gaps leave the agent uncertain about the tool's side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description's 'by ID' merely reiterates the schema's phase1_id description and provides no additional parameter semantics beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'update' and clearly identifies the resource as 'IPsec Phase 1 (IKE) entry' with the requirement 'by ID'. This distinguishes the tool from sibling tools like create_ipsec_phase1, delete_ipsec_phase1, and update_ipsec_phase2.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states it is for an existing entry and requires an ID, providing clear context for when to use it. However, it does not explicitly mention alternatives (e.g., create for new entries) or the need to call apply_ipsec_changes after updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description is consistent. However, it does not disclose that changes may require a separate apply step (e.g., apply_wireguard_changes) or explain the effect of apply_immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and target. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and lacks update workflow context, such as whether only provided fields are updated or if changes need to be applied separately. Despite rich schema and output schema, the description leaves ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter documented. The description adds no parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing WireGuard tunnel by ID', using a specific verb and resource. It distinguishes itself from create/delete/search siblings by specifying the operation and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for modifying an existing tunnel but does not provide explicit when-to-use vs alternatives. It lacks mention of prerequisites like obtaining the I/D from search_wireguard_tunnels or differentiating from update_wireguard_peer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, but the description adds the crucial consequence 'irreversible', which goes beyond the annotation. It does not mention dependencies or the confirm/dry_run safety gate, but those are covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, action first, with a clear 'WARNING: This is irreversible.' every word earns its place with no filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations are rich, and the irreversible warning is valuable, but the description lacks context about when to use this tool and what the deletion implies for dependent routing or firewall objects. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for group_id, confirm, dry_run, and apply_immediately. The description adds no parameter-level semantics beyond restating 'by ID', so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('gateway group'), and the lookup key ('by ID'). This distinguishes it from sibling tools like create_gateway_group, update_gateway_group, and search_gateway_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that search_gateway_groups should be used to obtain the ID or that update_gateway_group is the correct tool for modifications, leaving the selection entirely to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds the explicit warning 'This is irreversible,' which is valuable behavioral context beyond the structured hint. It conveys that the deletion cannot be undone, complementing the safety-related schema parameters (confirm, dry_run) without conflicting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus a warning, front-loaded with the action and object. Every word earns its place; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a rich output schema and annotations, the description is minimally adequate. However, it omits any mention of safety gates like confirm or dry_run, and the apply_immediately parameter, which are significant for a destructive operation. The warning about irreversibility adds some completeness, but the absence of usage context keeps it at a moderate level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add parameter-specific meaning beyond restating deletion by ID; all parameter semantics are already in the schema. No extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), the resource (IPsec Phase 1 encryption algorithm entry), and the method (by ID). It is specific and distinguishes from sibling tools like create/update/search operations and phase2 deletions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention how to obtain the encryption_id (though the schema references search_ipsec_phase1_encryptions), nor does it state any prerequisites or exclusions. For a deletion tool, this is a notable gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already convey (readOnlyHint=true, destructiveHint=false). It does not disclose any additional traits such as whether the settings are cached, what specific settings are returned, or any authentication requirements. The output schema may cover return values, but the description itself contributes nothing beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's action and subject. It contains no fluff or redundant words, achieving high efficiency and front-loading.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, read-only, output schema present), the description is complete. It accurately identifies the resource and operation, and the output schema covers return value details, so no further context is required. The presence of a output schema means the description need not explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and schema coverage is 100%, so there is no parameter information to add. With 0 params, the baseline is 4, and the description correctly needs no param explanations. The simple 'Get the current HAProxy service settings' suffices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly names the verb 'Get' and the resource 'current HAProxy service settings', identifying it as a read operation. It distinguishes itself from sibling getters like get_gateway_status or get_webgui_settings by explicitly targeting HAProxy settings, and from HAProxy mutation tools like update_haproxy_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that it pairs with update_haproxy_settings for modifications or that other HAProxy read tools (e.g., search_haproxy_frontends) exist. There is no explicit when/when-not or alternative tool reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no additional behavioral context beyond restating the 'get' operation, such as return format or system impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear subject-verb-object structure. It is appropriately concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only getter with an output schema and annotations, the description is sufficient. It doesn't need to explain return values because the output schema handles that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The description correctly doesn't discuss parameters, and the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the specific resource 'system log settings', distinguishing it from sibling getter tools like get_webgui_settings and get_email_notification_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other configuration getter tools. The description simply states the action without any context or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds no additional behavioral context such as potential large responses, whether the table must exist, or error behavior. It neither contradicts nor enriches beyond the annotations, earning a baseline 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy. It directly communicates the tool's purpose without wasting words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter with read-only annotations and an output schema present, the description is sufficiently complete. It covers the essential purpose, and the schema and annotations fill in the remaining context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter 'name' is well described with examples. The description itself adds no parameter meaning beyond what the schema provides, so the baseline 3 applies for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the contents of a specific pf firewall table. The verb 'Get' and resource 'contents of a specific pf firewall table' are specific and distinguish it from siblings like search_pf_tables (which lists tables) and get_pf_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that the table name should come from search_pf_tables or that this is for inspecting a known table's contents. The schema parameter hint does not count because the description itself should carry this information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) already indicate mutation, but the description adds no extra behavioral context such as the need for confirm=True on delete, immediate application default, or any side effects. This is a notable gap for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no filler. Clearly communicates the core purpose in minimal words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description is a minimal viable entry point. Given the tool handles two distinct operations (create/delete) with different required parameters and a safety gate, the description does not address these nuances, but the schema and output schema compensate partially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already described in the schema (e.g., 'used for create', 'required for delete'). The description itself adds no parameter semantics, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Add or remove') and the resource ('a server from an HAProxy backend'), making it distinct from sibling tools like search_haproxy_backend_servers or create_haproxy_backend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use the tool (add or remove backend servers) but does not explicitly list alternatives or when-not-to-use scenarios. However, the action parameter adds clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety profile (write, idempotent, non-destructive). The description adds minimal context: 'sends the account key to the ACME server and completes registration'. This clarifies the mechanism but does not disclose additional behaviors such as network dependencies, failure conditions, or external service side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the first sentence clearly stating the purpose. The second sentence adds some redundancy ('sends... and completes registration') but still provides a slight mechanistic clarification. Overall, it is efficient with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one well-schema'd parameter, strong annotations, and an output schema, the description is adequately complete. It lacks explicit context about the surrounding ACME workflow (such as needing a created key first), but the purpose and parameter are clear enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the single parameter 'id' with a clear description: 'Account key ID to register (from search_acme_account_keys)'. Schema coverage is 100%, so the description does not need to add parameter details. No additional parameter semantics are provided in the tool description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Register an ACME account key with the ACME server (Let's Encrypt)'. It uses a precise verb ('register') and resource ('ACME account key'), and distinguishes itself from sibling tools like 'create_acme_account_key' by specifying the target ('ACME server') and the completing-registration action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is implied rather than explicit. The description indicates registration with the ACME server but does not specify when to use this tool versus alternatives, nor does it mention prerequisites (e.g., key must already exist). The parameter description hints that the ID comes from 'search_acme_account_keys', providing some indirect context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is clear. The description adds minimal behavioral context by noting filtering and pagination, but it does not go beyond the schema and does not describe result behavior or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no unnecessary details and effectively communicates the core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema and strong annotations, the definition is minimally viable for a simple search tool. However, it lacks any guidance on how this search differs from many related search interfaces and does not articulate any non-goals or limitations, making it incomplete for tool-selection context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters (page, sort_by, page_size, search_term) are fully documented in the schema with types, defaults, and descriptions, so the schema coverage is 100%. The description only generically references filtering and pagination without adding additional meaning to any specific parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and names the resource 'interface bridges', clearly distinguishing it from sibling tools like create_interface_bridge and get_available_interfaces. The mention of 'filtering and pagination' adds functional scope and reinforces the search behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a lookup use case via the word 'Search' and the read-only annotations, but it provides no explicit guidance on when to choose this tool over alternatives such as search_interfaces, search_interface_configs, or search_interface_groups. It does not mention exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, which are already disclosed structurally. The description adds context about client-side filtering via search_term, which is useful. However, it does not disclose pagination behavior details (e.g., default page size, limits, response structure) beyond what the schema already states. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that covers the main purpose, filtering, and pagination. It is front-loaded with the key action and resource, and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple read-only search with no required parameters, a full output schema, and comprehensive parameter descriptions, the description is adequately complete. It could mention response structure, but the output schema compensates. The lack of guidance on when to use this vs. sibling search tools is a minor gap, but overall this is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds the meaning of 'search_term' as a client-side filter, which complements the schema. It also implies that search_term covers group name/description, matching the schema's parameter description. Overall, the description adds nuance to the search behavior without the need to repeat all parameter docs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search interface groups with filtering and pagination' clearly states the tool's verb (search) and resource (interface groups), and mentions filtering and pagination. Although it does not explicitly differentiate from sibling tools like 'search_interfaces' or 'search_interface_configs', the resource 'interface groups' is specific enough 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching interface groups with optional filters, and the parameter names provide pagination context. However, no explicit guidance on when to use this tool versus alternatives (e.g., search_interface_configs, search_interface_bridges) is provided, and no exclusions or alternative tool mentions are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is a safe read operation. The description adds only generic 'filtering and pagination' which is fully covered by the input schema, providing no additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is perfectly concise and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With complete schema coverage, an output schema, and annotations, the description is sufficiently complete for a simple search tool. There are no hidden gaps; filters and pagination are fully described in the schema, and return values are handled by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all five parameters. The description adds no parameter-level detail, and the baseline of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool searches WireGuard peers, which is a specific verb+resource. It clearly distinguishes from sibling tools like create_wireguard_peer or delete_wireguard_peer, and from search_wireguard_tunnels which covers a different entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when looking for WireGuard peers, but provides no explicit guidance on when to use this tool vs alternatives, nor any exclusions. It doesn't mention that searching tunnels is a different operation, so usage context is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds no behavioral context beyond the name and parameter schema. It doesn't mention that changes may require applying DHCP changes or the effect of apply_immediately, so it adds little value beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence that says exactly what the tool does with no fluff. It is appropriately sized for a simple update operation and front-loads the key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but the schema and annotations provide substantial context. It doesn't mention the workflow around applying changes or that the pool must exist, though 'by ID' hints at it. The apply_immediately parameter is documented in the schema but not called out in the description, so the agent might miss the nuance that changes may not take effect unless applied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 itself provides no additional parameter meaning; it only repeats 'by ID' which the schema already documents via pool_id description. No extra semantic value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('DHCP address pool'), and the scope ('existing... by ID'). It distinguishes this from create/delete/search tools in the sibling list. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies appropriate use: it says 'existing' and 'by ID', indicating the pool must already exist and be identified via search_dhcp_address_pools. It doesn't explicitly name alternatives, but the verb and resource make the usage context clear. No exclusionary guidance provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the basic mutation profile is known. The description adds no additional behavioral context (e.g., that rule IDs can shift, or that apply_immediately controls when changes take effect), but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and object. Every word is necessary; there is zero waste or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The rich schema (14 parameters, all described) and annotations provide sufficient detail for correct invocation, including return handling via an output schema. However, the description alone lacks high-level guidance about workflow (e.g., using search_firewall_rules to obtain rule_id, or the need to apply changes separately if apply_immediately is false), making it minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter coverage, including crucial semantics like rule_id being an array index from search_firewall_rules and verify_descr as a safety check against ID shifts. The description itself adds no parameter information, so it relies entirely on the schema, which is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('update') and resource ('existing firewall rule') with an addressing mechanism ('by ID'), making it unambiguous. It clearly distinguishes from sibling tools like create_firewall_rule_advanced, delete_firewall_rule, and move_firewall_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you want to modify a rule) but does not explicitly state when to use it vs alternatives or provide prerequisites like searching for the rule first. No exclusions or when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 'by ID' as a targeting detail but does not disclose partial update semantics or the role of apply_immediately. It does not contradict the annotations, but it adds little beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of 7 words: 'Update an existing NAT port forwarding rule by ID'. It is front-loaded with the action and resource, contains no redundancy, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 12 parameters and a mutation operation, but the description is extremely terse. It lacks context on when to use it versus alternatives and does not mention that only specified fields are updated or that apply_immediately controls whether changes take effect immediately. The rich schema and annotations compensate for parameter and safety details, but the description remains minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description itself contains no parameter information, but the input schema has descriptive text for all 12 parameters, including crucial context like port_forward_id being an array index from search_nat_port_forwards. With 100% schema coverage, the description need not add more.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and identifies the resource ('NAT port forwarding rule') with an identifier ('by ID'). This clearly distinguishes it from sibling tools like create_nat_port_forward and delete_nat_port_forward through the word 'existing' and the targeting mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing' implies this tool is for modifying already-created rules, but the description provides no explicit guidance on when to use it versus alternatives (e.g., create, delete, or apply_nat_changes). It does not mention prerequisites such as obtaining the port_forward_id from search_nat_port_forwards, though the schema hints at this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the basic mutation and safety profile. The description adds no further behavioral context, such as what happens with apply_immediately or whether changes require a restart, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 23 parameters, but an output schema exists and the input schema covers all parameters. The description is minimal but sufficient for a straightforward update operation; however, it lacks broader context like the availability of sibling search tools for ID discovery or the role of apply_immediately, so it is not fully complete for a complex operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 23 parameters are already documented with descriptive names and descriptions. The description adds no additional parameter-level meaning, leaving the schema to carry the full burden, which aligns with the baseline of 3 for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update'), the resource ('OpenVPN client instance'), and the identification method ('by ID'). It distinguishes this tool from sibling tools like create_openvpn_client, delete_openvpn_client, and update_openvpn_server by focusing on updating an existing client.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing OpenVPN client (as opposed to creating a new one via 'create_openvpn_client'), but it does not explicitly provide when-to-use guidance, mention alternatives, or explain prerequisites such as first calling search_openvpn_clients to obtain a valid client_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which communicates the safety profile. The description adds little behavioral context beyond 'existing' and 'by ID', and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. It conveys the essential action, target resource, and key requirement in only eight words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich schema, annotations, and an output schema, the description does not need to restate parameter or return details. However, for a 9-parameter mutation tool, some guidance about partial updates (e.g., only provided fields are changed) or the need to obtain user_id from search_users would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter schema fully documents all nine fields including their descriptions and defaults. The description does not add parameter-level semantics beyond highlighting user_id via 'by ID', but the baseline of 3 is appropriate given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' with a clear resource ('existing pfSense local user') and method ('by ID'). It immediately distinguishes this tool from create_user, delete_user, and search_users by focusing on updating an already-existing user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing' and 'by ID' implicitly suggests this tool is not for creating users and that a user ID is required, likely obtained from search_users. However, it does not explicitly state when to use this tool over create_user/delete_user or mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveness, but the description adds that it operates on the 'live' firewall and creates block rules, which gives concrete behavioral context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus a short warning, front-loading the main action and avoiding unnecessary detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and output schema, the description adequately covers purpose and key behavior. It could mention the need to apply firewall changes, but this is implied by sibling tools and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are already fully described in the schema (100% coverage), so the description adds no extra parameter-level meaning. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Block') with a clear resource ('multiple IP addresses') and context ('live pfSense firewall'). It also clarifies the effect ('Creates block rules'), distinguishing it from read-only tools and single-rule creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like create_firewall_rule, nor does it mention the confirm/dry_run safety gates. The 'WARNING' only cautions about destructiveness, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds 'WARNING: This is irreversible,' which strengthens the destructive context and clarifies permanence beyond the annotation. It does not mention the confirm or dry_run safety gates, but those are clearly documented in the schema. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the purpose and a clear warning. Every word earns its place, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (all parameters described) and annotations, the description covers the core action and the key risk (irreversibility). It could additionally mention the safety gates (confirm/dry_run) in prose, but the schema already handles that. The description is adequate for a simple delete tool with strong structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds no extra meaning about parameters beyond what the schema already provides. It does not clarify the relationship between confirm, dry_run, and actual deletion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an alias by ID' uses a specific verb and resource, clearly identifying the action and target. It distinguishes this tool from sibling tools like create_alias, update_alias, and search_aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or conditions (e.g., 'use this for deleting aliases, not for managing addresses'). The tool name is self-explanatory, but the description offers no explicit usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WARNING: This is irreversible', which complements the destructiveHint=true annotation by specifying the permanence of the action. This is useful undisclosed context, though it could optionally mention effects on dependent certificates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a direct statement and an explicit warning. Every word is purposeful, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive operation with a well-documented schema and output schema, this description is sufficient. It lacks usage guidance for safety but compensates partially with the warning. The overall context is clear for an agent to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% description coverage for all three parameters, including the confirm gate and dry_run preview. The description adds no additional parameter semantics beyond what the schema already conveys, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a Certificate Authority by ID', providing a specific verb and resource. This clearly differentiates from sibling delete tools such as delete_certificate and delete_crl by targeting the Certificate Authority specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives, nor does it mention the confirm and dry_run safety parameters. The irreversibility warning is cautionary but does not direct the agent on usage or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive, but the description adds the explicit warning 'This is irreversible,' providing important context about the permanent nature of the deletion. It does not contradict annotations and goes beyond the structured safety flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear warning, highly concise and front-loaded. Every word contributes to understanding the tool's purpose and risk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive delete operation, the description is adequate, especially with the warning and the schema covering the confirm and dry_run safety gates. It could mention the prerequisite of listing revisions first, but the schema's reference to get_config_history covers that. Output schema exists, so return value details are unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for revision_id, confirm, and dry_run. The description adds no additional parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), the resource (configuration history revision), and the identifier (by ID). It distinguishes itself from sibling tools like get_config_revision and restore_config_backup by specifying deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as get_config_history for listing or restore_config_backup for restoring. It does not mention prerequisites or exclusions, leaving the user to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds 'WARNING: This is irreversible' which provides consequence context beyond the destructiveHint annotation. However, it does not mention the confirm safety gate or apply_immediately behavior, which are covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence plus a warning, front-loaded with the action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With destructiveHint annotation, full schema coverage, and an output schema, the description is adequate for a destructive tool. It could mention the confirm gate, but the schema covers that, so no critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% parameter description coverage, so the description adds no new parameter meaning beyond what is already in the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Delete'), the resource ('DHCP static mapping'), and the identifier ('by ID'), distinguishing it from sibling tools that create, update, or search mappings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., update to disable) or any exclusions. The description only states what it does, not when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds a meaningful 'irreversible' warning, which goes beyond the annotation's generic destructiveness. It does not mention the confirm/dry_run safety gates, but those are fully described in the schema, so no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the action front-loaded and the warning delivered immediately. Every word earns its place, and there is no repetitive or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description combined with 100% schema coverage, annotations, and an output schema is nearly complete. It adds the important irreversibility caveat, though it could mention that confirm=true is required to execute, but the schema already covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds no parameter-specific detail beyond saying 'by ID', while the schema already explains override_id source and safety flags. The description provides no extra semantic value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a DNS Forwarder host override by ID, using a specific verb and resource. It distinguishes from nearby sibling tools like delete_dns_host_override and delete_dns_domain_override by naming 'DNS Forwarder' explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as delete_dns_host_override or delete_dns_domain_override. It does not mention prerequisites like searching for the ID first or that confirm must be true to execute, leaving usage entirely implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds valuable context beyond that: the deletion is irreversible and operates on the live appliance. This goes beyond the bare annotation and conveys the permanence and direct impact of the action. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus an explicit warning. It is front-loaded with the core action and includes no filler, earning every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (5 parameters, full coverage) and presence of both output schema and annotations, the description is reasonably complete for a delete tool. It adds the key caveat of irreversibility. It is not overly verbose, and the schema fills in operational details like rule_id sourcing and the confirm safety gate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter (rule_id, confirm, dry_run, verify_descr, apply_immediately). Since the schema thoroughly documents parameter meaning, the description need not add more; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a firewall rule') and the target resource ('from the live pfSense appliance'), making it distinct from sibling tools like update_firewall_rule or search_firewall_rules. The warning about irreversibility reinforces the specific nature of this delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as obtaining the rule_id via search_firewall_rules. The only contextual hint is the cautionary warning, but there is no 'when-to-use' or 'when-not-to-use' framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but description adds the crucial context that deletion is irreversible, which is more specific than the annotation alone. This helps the agent understand consequences beyond the structured hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: action and object in the first, critical warning in the second. No wasted words, front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given rich annotations, full schema coverage, and an output schema, the description is mostly sufficient. It adds the irreversible warning not present elsewhere, though it lacks explicit note about applying changes or prerequisites, which are partly covered by parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 minimal parameter meaning ('by ID' aligns with frontend_id) but does not go beyond schema. No compensation needed due to full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Delete' and resource 'HAProxy frontend', clearly distinguishing from siblings like update_haproxy_frontend and delete_haproxy_backend. Reference to 'by ID' further clarifies the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 or when deletion is appropriate. The warning about irreversibility is cautionary but does not specify usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, and the description adds a useful warning that the operation is irreversible. It does not describe the confirm gate or dry_run behavior, but those are covered by the schema, so the added context is meaningful without being redundant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the verb, resource, and key identifier. There is no filler or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and all parameters fully described in the schema, the description only needs to convey the operation's essence and critical caveat. The irreversibility warning covers the main risk, making this sufficient for a simple destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 every parameter with descriptions. The description only mentions 'by ID' and does not add additional semantic detail beyond what the schema provides, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
'Delete a NAT port forwarding rule by ID' names both the action and the target resource, with the key parameter explicitly included. This distinguishes it clearly from sibling tools like update_nat_port_forward and search_nat_port_forwards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The only extra context is the irreversibility warning, which does not address selection among sibling tools such as update or search operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds 'WARNING: This is irreversible', clarifying that the operation cannot be undone—a behavioral trait beyond the annotation. No contradiction with annotations. It does not detail cascading effects, but the irreversibility warning adds substantial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal and front-loaded: one sentence stating the action plus a warning. Every word contributes, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% parameter coverage) and annotations (destructiveHint), the description covers the essential purpose and the key risk of irreversibility. It doesn't explain the confirm/dry_run pattern, but those are well documented in the schema, so the tool definition as a whole is complete enough. Lacks usage context, but that's covered in another dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (server_id, confirm, dry_run, apply_immediately) already described meaningfully. The description doesn't need to add parameter details and doesn't, so it neither helps nor hurts. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete an OpenVPN server instance by ID'), specifying both the verb and the resource. It distinguishes from sibling tools like delete_openvpn_client and update_openvpn_server. The irreversible warning adds urgency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention using search_openvpn_servers to find the server_id, nor does it state when not to use it. No exclusions or alternatives are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds 'WARNING: This is irreversible,' which goes beyond the structured hint by emphasizing the permanence of the action. While it doesn't mention the confirm safety gate or dry_run option, those are documented in the schema, and the warning provides meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with the core action stated first and the warning front-loaded. Every word earns its place, and there is no wasted or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, annotations, and output schema, the description is sufficiently complete for a simple delete operation. It includes a critical warning, and the schema covers parameter details. It could optionally mention the need to apply routing changes, but this is not essential for performing the delete itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (route_id, confirm, dry_run, apply_immediately) having a clear description. The tool description adds no additional parameter semantics, so it meets the baseline without compensating for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Delete') and the target resource ('a static route') with the specific identifier ('by ID'). This distinguishes it from sibling create/update/search static route tools, and the warning adds important context about the operation's nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, prerequisites (e.g., finding the route ID via search_static_routes), or the need to apply changes afterward. The schema parameter description mentions the ID source, but the tool description itself offers no usage context beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WARNING: This is irreversible', which goes beyond the destructiveHint annotation by clarifying the permanence of the action. It does not mention the confirm or dry_run parameters, but those are already documented in the schema. The added warning provides valuable context 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the action and target, the second delivers a clear warning. There is no redundancy or filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature, the description provides the essential warning and purpose. The schema covers all parameters and the output schema exists, so return values need not be described. It could be slightly more helpful by referencing search_users for obtaining the ID, but the schema already includes that context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 three parameters (user_id, confirm, dry_run). The description only reinforces that deletion is by ID, which aligns with user_id but adds no new parameter-level semantics. Baseline of 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('a pfSense local user'), and the identifier method ('by ID'). This distinguishes it from sibling tools like create_user, update_user, and search_users, which have different verbs and purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit when-to-use or when-not-to-use guidance. It implies that a user ID is required but does not mention that search_users should be used to obtain the ID, nor does it contrast with alternatives like updating or deactivating a user. The only guidance is a general warning about irreversibility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares destructiveHint=true and readOnlyHint=false, and the description's 'WARNING: This is irreversible' aligns with that without strictly adding new behavioral context. It reinforces the destructive nature but does not disclose additional side effects, permissions, or outcomes beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and includes a necessary warning. Every word is useful, with no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description is sufficiently complete when combined with the rich schema, annotations (destructiveHint), and output schema. The irreversible warning adds critical context, though it could mention operational consequences or steps like apply_immediately, but those are already visible in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to add parameter detail. The schema already explains vlan_id, confirm, dry_run, and apply_immediately. The description adds no extra parameter semantics, keeping the score at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a VLAN by ID' uses a specific verb and resource and clearly distinguishes the action from siblings like create_vlan, update_vlan, and search_vlans. The 'by ID' qualifier adds useful scoping that matches the vlan_id parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when a VLAN must be removed) but provides no explicit when-to-use/when-not-to-use guidance or alternatives. It does not mention prerequisites, such as looking up the VLAN with search_vlans or ensuring it is not in use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the warning 'This is irreversible', which goes beyond the destructiveHint annotation by specifying permanence. This is valuable context for a destructive operation, though it does not mention safety gates like confirm or dry_run (which are in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: a clear purpose statement and a necessary warning. It is front-loaded with the verb and resource, with no wasted words or repetitive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature, the description includes an irreversible warning, and the schema plus annotations cover confirm, dry_run, and destructiveHint. The presence of an output schema means return values are already documented. It could mention the confirm requirement explicitly, but this is present in the schema, so overall the description is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for all four parameters, including descriptions for confirm, dry_run, tunnel_id, and apply_immediately. The description only adds 'by ID', which is redundant with the tunnel_id field description, so no additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a WireGuard tunnel by ID', specifying a precise verb and resource. It distinguishes itself from sibling deletion tools like delete_wireguard_peer and delete_firewall_schedule by naming the exact object type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, such as updating a tunnel instead or using dry_run first. There is no mention of prerequisites or exclusions, leaving the agent to infer usage from the name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, so the description does not need to re-establish destructiveness. It adds the useful context that the client session will be terminated, but it does not mention whether this is reversible, whether confirmation is required (though the confirm parameter exists), or any side effects on other connections. The warning somewhat repeats the annotation without adding substantial new behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, front-loaded with the action verb and target. The warning is directly relevant and earns its place. No wasteful or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the presence of a destructive annotation, and a complete input schema that documents all parameters, the description is sufficient for safe operation. It could mention that confirm=true is required, but the schema already communicates this. The output schema presence means return values need not be described. The description covers the essential risk (session termination) in a straightforward way.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter (confirm, dry_run, connection_id) already has a defining description. The tool description adds no parameter-specific meaning beyond what the schema provides, which is acceptable given full coverage. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Disconnect') and resource ('OpenVPN client connection'), clearly distinguishing it from sibling tools like delete (which removes config) or update (which modifies settings). It is unambiguous about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for actively connected OpenVPN clients but does not explicitly state when to use this tool versus alternatives (e.g., disabling the client, deleting the client, or stopping the OpenVPN service). No exclusions or alternative tool references are provided, though the context of disconnecting a live session is clear enough for basic guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveness, but the description adds concrete behavioral scope: it modifies a server-wide setting via PATCH, affects ALL API consumers, and is not limited to the current MCP session. This enriches the risk profile and provides context beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and followed by a critical warning. Every word earns its place, and it avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema, the description covers the essential context: the global impact and the specific endpoint. It could mention that disable_hateoas can reverse the change, but this is not strictly necessary given the sibling list and the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the only parameter (confirm) with a clear description, and the tool description does not add additional parameter-specific semantics. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Enable HATEOAS links in API responses on the pfSense server.' This is a specific verb+resource combination that distinguishes it from the sibling tool disable_hateoas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no direct guidance on when to use this tool versus alternatives like disable_hateoas. The warning about global impact implies caution but does not explicitly state when to choose this tool or when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the constraint that the link must come from a previous API response, which is a meaningful behavioral trait beyond the schema (though the parameter description also mentions '_links section'). No contradictions detected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with exactly nine words, fully front-loaded, and contains no filler or redundant content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, clear annotations, and an output schema, so the description only needs to convey the core purpose and any key constraints. It does this adequately. A minor gap is the lack of explicit note about HATEOAS being enabled, but this is implied by the mention of links from previous responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage with a description ('The link URL to follow (from _links section)'). The tool description adds no new 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Follow') and a specific resource ('HATEOAS link') and clearly indicates the source ('from a previous API response'). This distinguishes it from sibling tools like enable_hateoas or disable_hateoas, which manage HATEOAS behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: it should be used when a client needs to navigate a HATEOAS link returned in a prior API response. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds the constraint that the certificate must be signed by an existing CA, which is useful context. However, no additional behavioral traits such as side effects or prerequisites are disclosed beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 10 words, front-loaded with the action and object. It is concise, clear, and contains no wasted information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter certificate generation tool, the description is minimal but sufficient when combined with full schema documentation and an output schema. It covers the key prerequisite ('existing CA') and the core purpose. It lacks explicit usage guidance but is not incomplete enough to warrant a lower score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all 9 parameters with descriptions covering 100% of the schema. The description itself adds no parameter-level detail beyond what is already in the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Generate), the object (a new certificate), and the specific scope (signed by an existing CA on pfSense). This distinguishes it from create_certificate or create_certificate_authority, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that an existing CA is required, but it does not explicitly state when to use this tool over create_certificate or renew_certificate. No alternatives are named or exclusions given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clearly established. The description adds the word 'current' to indicate live settings rather than defaults, but does not disclose what the output structure looks like or any behavioral nuance (e.g., behavior if BIND is not installed). This is acceptable but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and resource. It contains zero filler or redundant information, making it perfectly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter tool with no parameters and an existing output schema, the description is sufficient to convey the core purpose. However, it lacks sibling differentiation and any note about when to choose BIND settings over other DNS settings, which would have made it fully complete. Still, it is adequately complete for the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema covers 100% of them (none). The description therefore does not need to explain any parameter semantics. The baseline for 0 params is 4, and the description adequately handles this by not introducing irrelevant detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and names the exact resource 'BIND DNS server settings', making it clear this fetches BIND settings. This distinguishes it from sibling tools like get_dns_resolver_settings (Unbound) and get_dns_forwarder_settings (dnsmasq), which target different DNS services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_dns_resolver_settings or get_dns_forwarder_settings. The tool name implies BIND, but there is no explicit statement of when this is the appropriate choice or when to select a different DNS settings tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds a small amount of context by listing example content (pool ranges, lease times), but it does not disclose any further behavioral traits such as return format, pagination limits, or potential side effects. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and resource. It contains no redundant or filler content, and every word adds value by specifying what the tool retrieves.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature, the presence of readOnlyHint/destructiveHint annotations, full schema coverage, and an output schema, the description is sufficiently complete. It could be improved by explicitly mentioning that it returns all interfaces when none is specified, but that is already documented in the interface parameter schema. Overall, no significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (page, interface, page_size), so the schema already provides clear semantics. The description itself does not add additional parameter meaning, merely listing content types rather than parameter details. This meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('DHCP server configuration'), and provides concrete examples of what it includes (pool ranges, lease times). This clearly distinguishes it from the sibling update_dhcp_server_config and related DHCP tools like search_dhcp_leases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for reading the DHCP server config, which is contextually clear given the sibling update_dhcp_server_config. However, it does not explicitly state when to use this tool vs alternatives, nor does it mention filtering or pagination behavior beyond what the schema provides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the resource name, which is already in the tool name, and offers no additional behavioral context such as return format, permission requirements, or whether it reads live or saved configuration.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler words. It efficiently communicates the tool's purpose without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with an output schema present, the description is adequate. It clearly states what is retrieved, and the output schema likely covers the return fields. Minor ambiguity remains about whether it returns the running configuration or saved settings, but this is not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty with 100% coverage, so the baseline score of 4 applies. The description does not need to explain parameter formats since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and explicitly identifies the resource ('DNS Forwarder (dnsmasq) service settings'). This clearly distinguishes it from the similar sibling tool get_dns_resolver_settings, which presumably retrieves different DNS service settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention get_dns_resolver_settings or any other related DNS tools, leaving the agent to infer the appropriate context without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds 'all OpenVPN servers' as useful scope context, but does not disclose return format, potential emptiness, or any operational nuances. However, for a simple read-only status getter, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that directly states the tool's purpose. It is front-loaded with the verb and object, contains no redundant information, and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has no parameters, read-only annotations, and an output schema (not shown but indicated to exist), the description is largely complete. It does not explain return values (schema covers that), but it could have briefly distinguished itself from get_openvpn_status to prevent confusion. Still, for a simple status getter, the description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, and the schema coverage is 100% vacuously. The description correctly implies there are no inputs. Baseline for zero-parameter tools is 4; no additional parameter information is needed or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get'), the resource ('status of all OpenVPN servers'), and the scope ('all'). It distinguishes itself from siblings like get_openvpn_client_status by specifying servers, and from get_openvpn_status by focusing on all servers individually.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_openvpn_status or search_openvpn_servers. There is no mention of prerequisites or conditions under which this tool is the preferred choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a specific consequence ('This will power off the system') beyond the destructiveHint annotation, clarifying that the operation is not just destructive but a hard shutdown. This helps the agent understand the irreversible nature, though it could mention that the system remains off until manually powered on.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one action sentence plus a warning. Every word earns its place, and the critical warning is front-loaded for immediate visibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive operation, the description, combined with the rich parameter schema and annotations, is sufficiently complete. It could have included a note about using dry_run first, but the schema already documents this capability, so the gap is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters (confirm and dry_run) with clear descriptions, so baseline is 3. The tool description adds no additional parameter-specific meaning, but none is needed given the schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Halt (shut down) the pfSense system.' It also distinguishes from the sibling reboot_system by explicitly specifying that the system will be powered off, making the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like reboot_system. The warning indicates caution but does not state explicit use cases, exclusions, or prerequisite conditions (e.g., 'only when full shutdown is required').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds no behavioral context beyond that—e.g., whether delete requires a confirm flag, if changes apply immediately, or what gets affected. It doesn't contradict annotations, but it also doesn't disclose any operational side effects or safety gates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and front-loaded: a single action line followed by a brief explanatory sentence. Every word contributes to scope or purpose, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 17-parameter CRUD tool, the description provides adequate high-level context, while operational details like required fields and delete confirmations are already in the schema. The output schema further reduces the need to explain return values, making the description sufficiently complete for orientation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions, so the schema carries the burden. The description's examples (static IPs, custom routes, blocking) loosely map to tunnel_network, custom_options, and block, but don't add meaning beyond the schema's existing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb+resource: 'Create, update, or delete an OpenVPN Client Specific Override (CSO).' It also unpacks what CSOs are used for (static IPs, custom routes, blocking clients), making the purpose unambiguous and distinguishing it from read-only sibling tools like search_openvpn_csos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage scenarios: assigning static tunnel IPs, pushing custom routes, or blocking clients. This implies when the tool is appropriate, though it doesn't explicitly mention when not to use it or name a read-only alternative for viewing CSOs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the agent already knows this is a mutation but not destructive. The description adds almost no behavioral context beyond the word 'existing'—it doesn't mention side effects, prerequisites (e.g., CA connectivity), whether certificates are regenerated, or if renewal is asynchronous. This is a significant gap for 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that is front-loaded with the verb and resource. Every word earns its place, with no unnecessary padding or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the operation (one parameter, output schema exists), the description is adequately complete for basic invocation. It doesn't explain return values, but the output schema covers that. It could be improved by mentioning potential failure modes or prerequisites, but for a low-complexity tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter, with a helpful description explaining the certificate_id is an array index from search_certificates. The tool description itself adds no additional parameter semantics, but the schema already does the heavy lifting. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('renew') and resource ('existing certificate') along with the required input ('by ID'). It is distinct from sibling tools like create_certificate, update_certificate, and delete_certificate, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this when you have an existing certificate ID that needs renewal. It does not explicitly mention alternatives or exclusions, but the tool name itself differentiates from renew_acme_certificate, and the description implies the intended scenario. A brief mention of when not to use it would have made it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Search' is consistent. It adds no additional behavioral side effects (e.g., auth needs, rate limits) beyond what annotations already convey. The 'filtering and pagination' mention is a functional detail, not a behavior disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the core purpose and key features without any filler, making it optimally front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with four optional parameters, comprehensive schema descriptions, and an output schema, the description is adequate. It covers the essential purpose, but could benefit from mentioning default sorting/pagination behavior or the client-side filter nature of search_term (though schema already notes this). Overall, sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all four parameters described (page, sort_by, page_size, search_term). The description adds no parameter-specific semantics beyond the generic 'filtering and pagination', relying entirely on the schema for meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('ACME account keys'), and the key features ('filtering and pagination'). This directly distinguishes it from sibling tools like 'create_acme_account_key' and 'get_acme_settings'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching/listings but provides no explicit guidance on when to use it versus alternatives. No exclusions or alternative tool mentions are given, so the context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the contextual detail that it covers LDAP and RADIUS servers but does not disclose additional behavioral traits like pagination behavior or return format, though an output schema exists to cover those.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. Every word earns its place, and it is appropriately sized for a simple search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool, the output schema, and full schema coverage for parameters, the description is nearly complete. It clearly identifies the resource and optional filtering. It does not explicitly state that it returns a list, but 'search' implies that, so a slight deduction for that omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (page, sort_by, page_size, search_term) are documented in the schema. The description's mention of 'optional filtering' adds no new information beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' with a clear resource 'pfSense authentication servers' and specifies the types (LDAP, RADIUS). This clearly distinguishes it from other search tools for different resources like search_crls or search_ntp_time_servers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to search auth servers but does not explicitly state when to use it versus alternatives, nor does it provide exclusions. Since there is no alternative search tool for auth servers, the usage is implicitly understood but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add context beyond those. It adds the BIND package prerequisite and mentions filtering/pagination, but does not elaborate on response characteristics, rate limits, or other behavioral nuances. This is sufficient but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the tool's purpose, and includes a necessary prerequisite without any fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search/list tool, the description is complete enough given the presence of annotations and an output schema. It covers the core operation and prerequisite. It could be more explicit about alternatives, but that is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the schema already explains each parameter. The description only implicitly groups parameters into 'filtering' (zone_type, search_term) and 'pagination' (page, page_size), which adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search BIND DNS zones' with a specific verb and resource, and distinguishes it from sibling tools like create_bind_zone, update_bind_zone, and search_bind_zone_records. It also highlights filtering and pagination capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('Requires the BIND package to be installed on pfSense') which is useful for deployment context, but it does not explicitly state when to use this tool versus alternatives like search_bind_zone_records. Usage is implied by the tool name and description rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is clear. The description adds minimal behavioral context—'configured on pfSense' only scopes the search to system configuration. It does not mention pagination behavior or return characteristics, but output schema covers return values. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately and accurately conveys the tool's purpose. There is zero redundancy or filler, earning a top score for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only search function with an output schema available. The description sufficiently covers the resource and scope, and the schema fills in parameter details. It could benefit from an explicit pointer to sibling search tools, but the current description is adequate for its low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters (page, page_size, search_term) with clear explanations. The tool description adds no extra parameter information, so it does not go beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and names the exact resource 'Certificate Revocation Lists (CRLs)' with a scope qualifier 'configured on pfSense'. This clearly distinguishes it from sibling tools like create_crl, delete_crl, and search_certificates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching CRLs, but it does not explicitly state when to use it versus alternatives like search_certificates or search_certificate_authorities. The usage context is inferred from the resource name rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that filtering and pagination are supported, which is useful but not elaborated on (e.g., no mention of result format or default behavior). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loads the verb 'Search', and contains no filler. It is appropriately sized and immediately conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool with comprehensive schema descriptions and an output schema, the description is sufficient. It captures the essential behavior (searching with filtering and pagination) without needing to over-explain, though it could briefly mention the response is a list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with all four parameters clearly documented. The description's mention of 'filtering and pagination' only summarizes what the schema already defines, adding no new semantic detail beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Search DHCP server custom options' with a specific verb and resource. It distinguishes from sibling search tools by naming the specific resource type ('custom options'), and 'with filtering and pagination' adds scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and description—it is for searching DHCP custom options. However, there is no explicit guidance on when to choose this over other search tools or any exclusions/alternatives, so it does not fully meet the 'explicit' bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond the generic 'advanced filtering'—no mention of pagination behavior, client-side filtering, or result limits. This is acceptable but not enriched; the description does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler words. It is front-loaded with the action and resource, and every word earns its place. This is an ideal length given that the schema and output schema carry detailed information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter search tool with rich schema descriptions, annotations, and an output schema, the description is mostly complete: it identifies the resource and general capability. It does not explicitly mention pagination or the client-side 'search_term' behavior, but these are covered in the schema, so the description is sufficient for operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add parameter-specific meaning beyond what the schema already provides; it only states 'advanced filtering' generically. The schema's detailed parameter descriptions carry the full semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search DHCP leases with advanced filtering' uses a specific verb ('Search') and resource ('DHCP leases'), clearly distinguishing it from sibling tools like search_dhcp_static_mappings or search_dhcp_address_pools. The phrase 'advanced filtering' hints at the rich parameter set without overcomplicating the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the resource name ('DHCP leases') but does not explicitly state when to choose this tool over related alternatives such as search_dhcp_static_mappings or search_dhcp_address_pools. No exclusions or alternative tool names are provided, so the guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent understands this is a safe read operation. The description adds 'with pagination,' which is a behavioral trait beyond the schema, but it's minimal and mostly echoes the page/page_size parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states the core purpose and a key feature (pagination) with no wasted words. It front-loads the essential information effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple search tool with a complete input schema, safety annotations, and an output schema, the description provides sufficient context for a basic search operation. It could mention what an access list is or how it differs from BIND access lists, but that's not necessary for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter (page, sort_by, page_size) is already well-described in the schema. The description adds no additional parameter meaning beyond noting pagination, which is already represented by the page and page_size parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches DNS Resolver access lists, using a specific verb ('search') and a specific resource. It distinguishes from sibling tools like search_bind_access_lists by explicitly naming 'DNS Resolver'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and description: it's a read-only search for DNS Resolver access lists. However, no explicit alternatives or when-not-to-use guidance is provided, leaving the agent to infer context from the name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the search intent is clear. The description adds the DNS Forwarder host override scope, but it does not disclose any additional behavioral traits such as pagination, sorting, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the purpose without unnecessary details. It is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the annotations, and the presence of an output schema, the description is largely complete. It could strengthen usage guidance by explicitly distinguishing from DNS resolver alias searches, but the core information is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so page, sort_by, page_size, and parent_id are fully documented in the schema. The description does not add further parameter semantics beyond what the schema already provides, which is the baseline for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource construction: 'Search aliases for a DNS Forwarder host override.' It clearly identifies the resource (aliases) and the scope (DNS Forwarder host override), distinguishing it from sibling tools like search_dns_forwarder_host_overrides and search_dns_host_override_aliases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to find aliases tied to a specific host override, which gives context. However, it does not explicitly state when to use this tool versus alternatives (e.g., search_dns_host_override_aliases) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds the scoping constraint that the search is for a specific host override. It does not add much beyond that but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the verb and resource, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only search tool with full schema coverage and annotations, the description is adequate. It doesn't mention return format but the output schema covers that, and the sibling context makes the scope clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented. The description adds no additional meaning beyond what the schema says about parent_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('aliases for a DNS host override'), clearly distinguishing it from generic search_aliases and from DNS forwarder alias searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need aliases for a specific DNS host override, but it does not explicitly mention alternatives or when not to use it (e.g., versus the DNS forwarder variant).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read nature is known. The description adds 'filtering and pagination', which is useful but does not disclose deeper behavioral details such as client-side filtering or default ordering beyond what the schema indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. Every word serves a purpose, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, full parameter documentation, and read-only annotations, the description is sufficiently complete for a simple search tool. It lacks extra context like use cases or edge cases but meets the minimum for effective invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is documented. The description's mention of filtering and pagination maps to search_term and page/page_size, but it adds no additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and identifies the resource as 'gateway groups', clearly distinguishing it from sibling tools like search_gateways. It also mentions filtering and pagination, which further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a search use case but does not explicitly compare with alternatives or state when not to use it. Sibling tools like create/update/delete_gateway_group provide contrast, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds 'optional filtering and pagination,' which is useful but largely redundant with the schema. It provides no additional behavioral context beyond what annotations and schema already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and every word contributes meaning. It contains no filler or redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple search tool, full parameter descriptions, read-only annotations, and output schema, the description is adequate. It could optionally mention sort options or return behavior, but those are covered by the schema and output schema, making this complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly described. The description's mention of 'optional filtering and pagination' maps to the parameters but adds no new semantics beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('pfSense user groups'), and mentions optional filtering and pagination. This clearly distinguishes it from sibling tools like search_users or create_group, identifying exactly what the tool operates on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for searching user groups but does not explicitly state when to use it versus alternatives or provide any exclusions. There is no mention of when not to use it or relationship to tools like search_users or group management tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context about the scope of files (certificates, error pages, Lua scripts), but does not disclose additional behavioral details such as pagination behavior, sorting semantics, or that search_term performs a client-side filter. The description is consistent with annotations, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that leads with the verb and resource, followed by clarifying examples. No wasted words; it is efficiently front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and full parameter descriptions, the description covers the essential purpose and scope. It could benefit from mentioning that it searches file metadata/names, but the examples and schema are sufficient for basic selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all four parameters, so the schema already documents their purpose and defaults. The description does not add any parameter-specific meaning beyond what is already present, which aligns with the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Search') and resource ('HAProxy files'), supported by concrete examples of file types. This distinguishes it from sibling tools like search_haproxy_frontends and search_haproxy_backends, which target different HAProxy entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching HAProxy file-related items, but it does not explicitly state when to use this tool versus alternatives such as search_certificates or manage_haproxy_file. No exclusions or alternative recommendations are provided, so the guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which align with the search operation. The description adds only the behavioral detail of 'filtering and pagination', but does not disclose any additional side effects, rate limits, or operational nuances. With annotations covering the safety profile, this is adequate but not enriching.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main purpose and eliminates unnecessary words. Every element serves the goal of clarity without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-only search tool with complete parameter documentation and an output schema, the description is sufficient. It covers what the tool does, and the schema covers how to invoke it. A minor deduction for not mentioning any potential limitations or performance considerations, but overall complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides detailed descriptions for all four parameters (page, sort_by, page_size, parent_id) with 100% coverage. The description's mention of 'filtering and pagination' merely reflects the schema, adding no extra parameter-level meaning beyond what's already documented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: searching IPsec Phase 1 encryption algorithm entries. It uses a specific verb ('Search') with the exact resource, distinguishing it from create/update/delete operations and from Phase 2 search variants. The mention of filtering and pagination adds helpful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides basic context that the tool performs searching with filtering and pagination, but it does not explicitly state when to use this tool over alternatives like search_ipsec_phase1s or search_ipsec_phase2_encryptions. Usage guidance is implied through the name rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) already establish the safety profile, and the description adds only that the search supports filtering and pagination. It does not disclose whether this returns saved configuration entries versus live tunnel state, which is a meaningful behavioral distinction given the sibling get_ipsec_child_sa_status, but the annotation coverage lowers the bar.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that names the action, the resource (with clarifying parenthetical), and the key capabilities. Every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With read-only annotations, an output schema, and fully documented parameters, the tool definition covers most operational needs for an agent. The main gap is that 'entries' does not clarify whether these are configuration objects or live tunnel state, which matters given the sibling get_ipsec_child_sa_status tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all six parameters (mode, page, ikeid, sort_by, page_size, search_description) individually documented in the schema, so the baseline of 3 applies. The description's generic 'filtering and pagination' phrasing adds no semantic value beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') with a clear resource ('IPsec Phase 2 (Child SA / tunnel) entries') and states the scope ('with filtering and pagination'). It distinguishes from siblings like search_ipsec_phase2_encryptions and search_ipsec_phase1s by naming the exact object type being searched.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool for searching/listing Phase 2 configuration entries, but it does not explicitly state when to use it versus alternatives such as get_ipsec_child_sa_status for live tunnel status or search_ipsec_phase2_encryptions for encryption proposals. No exclusions or alternative-tool guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds only 'filtering and pagination,' which are already evident from the input schema, and does not disclose any additional behavioral traits such as client-side filtering or response formats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single six-word sentence that is fully front-loaded and free of redundancy. It earns its place without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (5 fully described parameters), annotations, and output schema, the description is sufficient for a straightforward read-only search operation. It lacks explicit context about result scope or comparison to sibling search tools, but the structured data compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description's mention of 'filtering and pagination' maps to the parameters but adds no additional semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Search' with the specific resource 'traffic shapers' and notes filtering and pagination, clearly distinguishing it from related sibling tools like search_shaper_queues or create_traffic_shaper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as search_shaper_queues or search_traffic_limiters. Usage is implied by the name and the word 'Search,' but no conditions or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds 'optional filtering and pagination,' but this largely mirrors the schema parameter descriptions and does not provide additional behavioral context such as result limits or search wildcard behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main purpose ('Search pfSense local users') and efficiently mentions the key features (optional filtering and pagination). Every word adds value, with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full output schema and complete parameter documentation, the description is sufficient for this simple read-only search tool. It clearly identifies the resource scope and optional filtering/pagination. It could be slightly more explicit about being read-only or directing to user management tools, but annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (page, sort_by, page_size, search_term) is already documented. The description adds no new parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search pfSense local users' with a specific verb and resource, and mentions optional filtering and pagination. It distinguishes itself from sibling tools like search_groups and search_auth_servers by targeting local users specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding/listing local users with filtering, but does not explicitly state when to use it over alternatives or when not to use it. No exclusions or alternative tool references are provided, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the safety profile. The description adds 'filtering and pagination' but does not elaborate on client-side filtering behavior or response structure. No contradiction with annotations, and the additional context is minimal beyond what annotations reveal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly communicates the purpose. There is no redundant or extraneous wording—every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full input schema, output schema, and read-only annotations, the tool is well-specified. The description is minimal but sufficient; it could optionally clarify the domain of 'virtual IPs' (e.g., CARP VIPs) but the combination of schema and annotations covers most operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 6 parameters (100% coverage), so the baseline is 3. The description's mention of 'filtering and pagination' aligns with the parameters but adds no additional meaning or clarification beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search'), the resource ('virtual IPs'), and the capabilities ('filtering and pagination'). It distinguishes from sibling tools like create_virtual_ip, update_virtual_ip, and delete_virtual_ip by focusing on read-only search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for searching/filtering virtual IPs, but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Given the sibling context, it's clear this is the search counterpart to CRUD operations, but no direct guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating, idempotent, non-destructive operation. The description adds no additional behavioral context such as partial-update semantics or side effects. With annotations covering the safety profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that is front-loaded with the action and object. Every word is meaningful, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the output schema exists and parameter descriptions are complete in the schema, the description is largely sufficient for a straightforward update operation. The only minor gap is not explaining the effect of apply_immediately or how to obtain the ID, but this is not critical for a simple CRUD tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all six parameters. The description adds no additional parameter-level meaning beyond highlighting the required 'override_id' via 'by ID,' which is already clear in the schema. Baseline 3 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource: 'Update an existing DNS domain override by ID.' It clearly identifies the exact object and action, distinguishing it from search/create/delete for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when updating an existing DNS domain override, particularly by providing its ID. However, it does not explicitly mention when not to use it or alternatives (e.g., host overrides, forwarder overrides), so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context beyond restating the operation; it does not mention apply_immediately semantics, defaultstatesize behavior, or potential side effects. With annotations present and no contradiction, this is acceptable but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, effectively front-loading the purpose. Every word earns its place, and it is appropriately sized for a simple update tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, the schema provides rich parameter descriptions, and annotations specify idempotence and non-destructiveness, the description is sufficient to inform an agent. It does not mention the related get_firewall_state_size or the apply_immediately default, but these are not essential given the schema and output schema. Overall, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, as all three parameters (maximumstates, defaultstatesize, apply_immediately) have descriptions in the input schema. The tool description itself adds no parameter-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and resource 'firewall state table size', clearly identifying the action and target. It distinguishes from sibling get_firewall_state_size by implying a mutation operation, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. The verb 'Update' implies it should be used to modify the firewall state table size, while the sibling get_firewall_state_size handles reads, but this is only implied, not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already indicating readOnlyHint=false, idempotentHint=true, and destructiveHint=false, the description adds the behavioral trait that the update targets an existing entity by ID. It does not disclose side effects like privilege replacement (which is covered in schema descriptions), but it does add some context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It says exactly what the tool does in the fewest possible words, earning its place without wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal, but combined with the output schema and comprehensive parameter descriptions, it is nearly sufficient. The lack of explicit guidance about what happens if optional fields are omitted is a minor gap, but annotations and schema fill most missing context, making the tool usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter details, but the input schema has 100% coverage with rich descriptions (e.g., 'List of privileges (replaces existing)'). Per the baseline rule, this earns a 3 without needing explicit parameter info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing pfSense user group by ID,' using a specific verb and resource. It distinguishes this tool from siblings like create_group, delete_group, and search_groups by specifying an update to an existing entity, with the ID as the targeting mechanism.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'existing' implies this tool is for groups that already exist, and 'by ID' suggests you need a known group ID, but no explicit alternatives or exclusions are given. The schema's group_id description refers to search_groups, but this is not part of the main description, providing only implied usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat these. The description adds minimal context ('existing', 'by ID') but does not disclose behavioral details such as the effect of apply_immediately, whether changes are staged, or if a reload is required. This is acceptable given the annotations cover the safety profile, but the description contributes little beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Update an existing HAProxy backend by ID.' It contains no filler words, tautologies, or redundant information, and it immediately conveys the core action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, a rich schema, annotations, and an output schema. The description is minimal but sufficient for an update tool: it identifies the target (existing backend) and the key identifier. It does not explain the apply_immediately parameter or update semantics, but those are covered by the schema's per-parameter descriptions. Overall, the description is complete enough for a moderately complex update operation, though it could benefit from a brief note about typical use cases or application behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (mode, name, descr, balance, backend_id, check_type, apply_immediately) already having a clear description in the input schema. The tool description adds no additional parameter semantics, but the schema fully compensates, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing HAProxy backend by ID' uses the specific verb 'Update' and clearly identifies the resource ('HAProxy backend') and the selection method ('by ID'). It distinguishes itself from sibling tools like create_haproxy_backend and delete_haproxy_backend by focusing on modifying an existing entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing HAProxy backend, but it does not explicitly state when to use this tool versus alternatives like create_haproxy_backend or delete_haproxy_backend. There is no mention of preconditions (e.g., backend must exist) or exclusions, leaving the agent to infer the appropriate context from the tool's name and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description accurately reflects a mutation operation ('Update') and adds no contradictory behavior. However, it provides no additional context beyond the annotations, such as whether updating an ID that doesn't exist will error, or whether partial updates are allowed. With annotations present, this is acceptable but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the verb and resource. Every word adds clarity, with no redundant filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has rich supporting structured data: a 13-parameter schema with 100% description coverage, annotations for idempotency and safety, and an output schema. Given this, the one-sentence description is adequate for an update operation. It could mention that the ID should come from search_ipsec_phase2s, but that is already in the schema's phase2_id description. Minor gap: no mention of the apply_immediately flag's effect, but that's in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 13 parameters. The description itself adds little parameter meaning beyond the required phase2_id. It confirms the update target is 'by ID', which aligns with the required parameter. Baseline 3 is appropriate given the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and identifies the exact resource ('IPsec Phase 2 (Child SA / tunnel) entry') with a key qualifier ('by ID'). This clearly distinguishes it from sibling tools like create_ipsec_phase2, delete_ipsec_phase2, or search_ipsec_phase2s.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage on existing entries via the word 'existing' and the ID requirement, but it does not explicitly state when to use this tool versus creating a new Phase 2 or deleting one. It also doesn't mention whether changes need to be applied separately (e.g., via apply_ipsec_changes), though the schema's apply_immediately parameter hints at this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate that the operation is not read-only (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds minimal context ('existing'), but does not disclose details like the apply_immediately parameter's effect, behavior on missing IDs, or whether it replaces or patches fields. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It states the action, target, and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the comprehensive parameter schema, output schema, and annotations, the description provides an adequate overview. It could mention that changes may be deferred via apply_immediately or that parent_id moves the range, but these are already documented in schema. The tool is a simple update operation, so the existing description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a clear description (e.g., time_range_id source, hour format, day-month pairing). The description adds no additional parameter details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') with a clear resource ('existing time range within a firewall schedule') and identifies the key identifier ('by ID'). It clearly distinguishes from sibling tools like create_schedule_time_range, delete_schedule_time_range, and update_firewall_schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (update an existing time range) but offers no explicit guidance on when to use this versus alternatives, no prerequisites (e.g., the need to obtain time_range_id from search_schedule_time_ranges), and no exclusions. It relies heavily on the tool name and sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the core behavioral profile. The description adds no extra context such as immediate application effects or error handling, so it adds no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler. Every word earns its place, and the structure is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple CRUD update, the description plus schema (6 parameters, full coverage) plus annotations (safety profile) plus output schema make it adequately complete. Missing details like non-existent VLAN behavior are not essential given the schema and annotations, though a bit more context on immediate vs staged application could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all six parameters are individually documented (e.g., pcp range, tag range, apply_immediately default). The description's 'by ID' adds no extra semantics beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description: 'Update an existing VLAN by ID' uses a specific verb ('update'), a resource ('VLAN'), and clarifies the target is an existing object. This distinguishes it from sibling create_vlan/delete_vlan operations through the verb and the word 'existing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives named. However, 'existing' implies not for creation, and the schema parameter vlan_id notes 'from search_vlans', giving a prerequisite. This provides implied usage but lacks explicit exclusions or sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds the explicit warning 'This is irreversible,' which reinforces the destructive nature with a stronger claim. However, it does not mention the confirm safety gate or dry_run preview, though these are documented in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely succinct: one declarative sentence plus a brief warning. Every word earns its place, and the warning is front-loaded to alert the agent to the tool's destructive nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complete schema, output schema, and destructive annotations, so the description does not need to explain return values or basic safety. However, it omits any mention of the typical workflow, such as whether apply_dns_resolver_changes must follow deletion to make changes effective, which is a notable gap given the sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully explains all four parameters including confirm, dry_run, and apply_immediately. The description itself adds no additional parameter context, so it does not exceed the baseline provided by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'DNS Resolver access list', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like create_dns_access_list, update_dns_access_list, and apply_dns_resolver_changes by specifying the destructive action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys that this tool is for deleting an access list, but it gives no explicit guidance on when to use it versus alternatives. It does not mention that one should use search_dns_access_lists to find the correct access_list_id, nor does it indicate whether apply_dns_resolver_changes is needed after deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, so the description adds extra context by explicitly warning that the operation is irreversible. This goes beyond the annotation's binary destructive flag, providing a meaningful behavioral detail. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single clear sentence plus a warning. Every word earns its place, and the main action is front-loaded. No unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema, annotations, and output schema provide rich structured context (e.g., confirm safety gate, client_id source). The description's irreversibility warning fills the key gap not covered by structured fields. For a simple delete tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description itself adds no parameter information beyond what the schema already provides. It does not mention the confirm or dry_run parameters, but the schema fully documents them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete an OpenVPN client instance') and the method ('by ID'). It is specific and distinguishes from siblings like search_openvpn_clients or update_openvpn_client. The warning about irreversibility reinforces the destructive purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites like the confirm parameter. The irreversibility warning implies caution but does not clarify when this tool is appropriate compared to update_openvpn_client or how to find the client_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral details beyond that: it enumerates all services, identifies stopped services, and checks CPU/memory/disk utilization. This is meaningful context without contradicting the safe-read annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a lead sentence establishing the tool's purpose, followed by a concise breakdown of the checks performed. Every clause adds value, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only diagnostic with an output schema, the description adequately covers the core behavior and scope. It could be slightly more complete by addressing its relationship to similar tools like get_system_health_report, but it is functionally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema confirms no required inputs, so there are no parameter semantics to clarify. The baseline for 0 parameters is 4, and the description appropriately focuses on behavior rather than parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a service health diagnostic, with a specific verb ('diagnoses'/'gets') and a concrete resource scope: all services, stopped services, and system resource utilization. It is distinct from narrow sibling diagnostics, but it does not explicitly differentiate itself from closely related tools like get_system_health_report.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Comprehensive service health check' implies a broad health-assessment use case, and the list of checks provides context. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives, which is notable given the many sibling diagnostic tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the filtering behavior (block/reject), which is the core function. However, it does not mention any limitations, such as whether the search includes both interface-specific and floating rules, or whether results are paginated. With annotations in place, this is acceptable but not rich in behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct, specific, and front-loaded with the action. There is no redundant wording, and every word contributes to clarifying the tool's scope. This is an example of efficient, well-structured description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no required parameters, output schema provided, and safe read annotations), the description fully covers what the tool does. The output schema likely explains return values, the parameter schema explains the filter, and the description explains the selection criteria. No additional context is necessary for an agent to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'interface' with a clear description ('Optional interface filter (wan, lan, etc.)'), and schema description coverage is 100%. The tool description does not re-describe the parameter, but the schema alone provides sufficient meaning. Baseline 3 is appropriate since no additional parameter context is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Find all firewall rules') with a precise scope ('that block or reject traffic'). This distinguishes it from generic rule listing tools like search_firewall_rules, which likely return all rules without the block/reject filter. The verb+resource+qualifier combination leaves no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the user wants to identify blocking/rejecting firewall rules, but it does not explicitly state when to use this tool versus alternatives such as search_firewall_rules, analyze_blocked_traffic, or get_firewall_log. No exclusions or alternative recommendations are provided, leaving the decision to the agent based on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing that this is a safe read operation. The description adds that it returns both the current count and the maximum, which is useful context. However, no further behavioral details are disclosed (e.g., whether the data is cached or if pagination applies), so the bar is adequately met but not exceeded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and elaborates with one additional clarifying sentence. Every word earns its place; it is both concise and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with an output schema and clear annotations, this description is complete. It explains the tool's function, what it returns, and the presence of an output schema covers the return structure. No gaps are evident.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty object). The description correctly implies none are needed, and there is no need to elaborate. This aligns with the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the specific verb ('Get') and resource ('firewall state table size and limits'). It also states the exact return value (active states and configured maximum), and it is distinct from sibling tools like update_firewall_state_size and search_firewall_states.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It is a simple getter, but there is no mention of monitoring use cases or exclusions (e.g., 'for individual states, use search_firewall_states').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no further behavioral context such as permissions, return format, or edge cases. It aligns with the read-only annotation but doesn't go beyond it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundant information. It is appropriately sized for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is complete. It clearly states what is retrieved and does not need to explain return values because the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description is not required to explain parameters. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly identifies the resource ('current system DNS server configuration'). It distinguishes itself from sibling tools like get_dns_resolver_settings and get_dns_forwarder_settings by focusing on the system-level DNS configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus related DNS tools. Given the many sibling tools for DNS settings, such as get_dns_resolver_settings and get_dns_forwarder_settings, the lack of explicit alternatives makes the usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds only the word 'current', which provides minimal extra behavioral context. It does not disclose any further traits (e.g., return format, caching behavior, or operational impact).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single five-word sentence that immediately states the verb and object. It is extremely concise with no wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, zero-parameter tool with an output schema, this description is fully sufficient. It states exactly what the tool does, and the output schema handles return-value documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema provides complete coverage. The description correctly adds no parameter information, and the baseline score of 4 applies for a zero-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Get') and the target resource ('current system timezone setting'), making its purpose unambiguous and distinct from siblings like update_system_timezone or get_system_hostname.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the correct tool for reading the timezone, but it does not explicitly mention when to use it versus alternatives such as update_system_timezone, nor does it state any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the main safety profile. The description adds the word 'current' to indicate it retrieves the live state, which is a minor behavioral detail. However, it does not disclose any other behavior such as whether the response is cached or what 'service settings' encapsulates beyond the schema. No contradiction with annotations; the added value is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and contains no filler or redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero parameters, the existence of an output schema, and annotations declaring it a read-only operation, the description is sufficient. It clearly states what the tool does, and the structured data fills in the return format and safety details. There are no gaps that would impede an agent from selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to add parameter semantics. The schema coverage is 100% vacuously. Per the rubric, a 0-parameter tool gets a baseline of 4, and the description does not detract from that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('current WireGuard service settings'), clearly indicating this is a read-only retrieval of the WireGuard service configuration. It distinguishes from siblings like update_wireguard_settings and search_wireguard_tunnels by focusing on service-level settings rather than modifications or tunnel-specific data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use this tool versus alternatives. It does not mention that this is the read counterpart to update_wireguard_settings or state any exclusions. Usage is only implicitly conveyed by the verb 'Get', which falls short of the rubric's requirement for clear context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the prerequisite that the ACME package must be installed, which is useful context. No other behavioral traits are disclosed beyond what annotations and schema already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, two sentences total. The first sentence states the purpose and key features (search, filtering, pagination) and the second provides a necessary prerequisite. There is no redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover the read-only and non-destructive nature, the description provides the essential missing context—the ACME package requirement. The tool is a straightforward search operation with well-documented parameters and return format, so nothing further is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters, so the schema carries the parameter semantics. The description does not add any additional parameter-level meaning beyond what the schema already provides, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches ACME (Let's Encrypt) certificates and mentions filtering and pagination. It also distinguishes this tool from less specific siblings like search_certificates by explicitly naming ACME.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite (ACME package installation) but does not provide explicit guidance on when to use this tool versus alternatives such as search_certificates. The intended use case is implied by the name and resource type, but no explicit exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds 'filtering and pagination' as behavioral context, but this is also evident from the schema. No additional details about return behavior, limits, or side effects are provided, but none contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence of nine words. It is front-loaded with the main action and resource, and every word is necessary. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of a rich output schema, and annotations confirming read-only behavior, the description is sufficient. It correctly identifies the resource and the key capabilities (filtering, pagination), and the schema fills in all parameter details. No critical context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for its four parameters, including meanings and examples (e.g., parent_id filter). The description only generically mentions 'filtering and pagination' without adding syntax or format details, so it adds no value beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') with a clear resource ('DHCP server address pools') and explicitly mentions filtering and pagination, distinguishing it from sibling tools like search_dhcp_leases or create_dhcp_address_pool. This makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its action and resource, but it does not explicitly state when to prefer this over alternatives (e.g., search_dhcp_leases) or when not to use it. No exclusions or alternative tool names are mentioned, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds 'filtering and pagination,' which is already evident from the schema and parameter names, providing minimal additional behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately states the verb and resource, followed by key capabilities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read-only search operation. Annotations cover safety, the output schema exists, and all parameters have descriptions. The description is sufficiently complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description does not add any parameter-specific semantics beyond what the schema already provides; 'filtering and pagination' is only a high-level summary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches outbound NAT mappings, using a specific verb and resource. It distinguishes itself from sibling tools like search_nat_port_forwards and search_nat_onetoone_mappings by naming the exact resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching outbound NAT mappings with filtering and pagination, but does not explicitly state when to use it over alternatives or mention any exclusions. No alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description's 'Search' is consistent with read-only behavior but adds no additional behavioral context such as return format, auth requirements, or rate limits. With annotations covering the safety profile, a neutral score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. Every word earns its place with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward search operation with a complete schema, annotations, and output schema. The description's mention of filtering and pagination covers the key behaviors, and nothing more is needed given the structured fields. It fully distinguishes the resource type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all 7 parameters (100% coverage), so the baseline is 3. The description only mentions generic 'filtering and pagination' without adding detail about specific parameters like mode, protocol, or search_term, adding little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search OpenVPN server instances' with a specific verb and resource, and also mentions filtering and pagination. This distinguishes it from sibling search tools like search_openvpn_server_connections and search_openvpn_clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It implies a search use case but does not mention exclusions or when to prefer it over other search tools. 'with filtering and pagination' adds only feature context, not usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose idempotency (idempotentHint: true), non-read-only nature, and non-destructive nature. The description adds no new behavioral detail beyond repeating 'idempotent'. It does not explain update semantics (e.g., partial update vs. replace) or authorization needs, but annotations mitigate some safety transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that front-loads the action and resource. The parenthetical '(idempotent)' is a useful trait but not redundant with the name. No filler or extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with multiple optional fields, the description does not specify the effect of omitted or null parameters—whether it performs a partial update or requires all fields. This is a meaningful gap for correct invocation. The presence of an output schema and annotations reduces the burden, but the update semantics are critical and not covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description including ca_id's origin. The description itself adds no parameter-level semantics, such as whether null means 'leave unchanged' or 'clear the field'. Baseline of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Update'), target resource ('existing Certificate Authority'), and scope ('by ID'). It distinguishes from sibling tools like create_certificate_authority, delete_certificate_authority, and search_certificate_authorities. The parenthetical '(idempotent)' is an attribute, not the core purpose, but does not obscure it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is clearly implied: use when modifying an existing Certificate Authority, as opposed to creating (create_certificate_authority), deleting (delete_certificate_authority), or searching. However, there is no explicit mention of when not to use it or reference to sibling alternatives, and the prerequisite of obtaining the ca_id from search_certificate_authorities is only in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutating, idempotent, non-destructive behavior. The description adds crucial behavioral context beyond this: the pfSense REST API fields are mirrored verbatim, and setting enableremotelogging=True is required for remote syslog to activate, otherwise remote-* fields are normalized back to null. This warns about a non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose, one for field naming convention, one for the critical remote syslog caveat. No filler, all content earns its place, and the most actionable warning is placed at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (25 parameters) and that an output schema exists, the description covers the main behavioral gotcha and field naming convention. It doesn't detail all side effects, but the schema and annotations provide adequate parameter and safety information. The description is sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning by explaining the enableremotelogging dependency and the normalization of remote-* fields, which is not evident from individual parameter descriptions. This helps the agent understand the interplay between parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Update the system log settings'. This is a specific verb + resource that distinguishes it from read-only tools like get_log_settings. However, it doesn't explicitly contrast with siblings such as update_webgui_settings or update_email_notification_settings, though the resource name 'log settings' provides adequate differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to update system log settings) but provides no explicit guidance on when to use it versus alternatives like get_log_settings. The only usage hint is the remote syslog enablement note, which is more about parameter configuration than tool selection. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is an idempotent, non-destructive write operation. The description adds the implementation detail of a POST request and the specific change categories affected, but does not disclose potential side effects like temporary service interruption.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the primary action and provide a brief, informative explanation without redundant wording. The description is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with full annotations and an output schema, the description gives sufficient context about what changes are applied. It does not explicitly mention prerequisites for pending changes, but this is reasonably implied. Slight room for improvement in usage guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description correctly requires no input. With no parameters to document, the baseline score of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: 'Apply pending DNS Resolver configuration changes' and specifies the scope by listing host override, domain override, access list, or settings changes. This distinguishes it from sibling apply_* tools such as apply_dns_forwarder_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied: the tool activates pending DNS Resolver changes, but the description does not explicitly state when to call it relative to making configuration changes or mention alternatives. It would benefit from stating that it should be used after modifying DNS resolver settings, not for DNS forwarder changes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds the purpose but no further behavioral traits such as prerequisites, side effects, or application behavior. With annotations present, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's core purpose without any filler. Every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (5 params, all described), annotations, and the straightforward create operation, the description is adequate for understanding the tool's role. It could mention side effects like whether changes are applied automatically, but the apply_immediately parameter implies that behavior, so the context is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of all 5 parameters with clear descriptions, so the baseline is 3. The tool description does not add semantic detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a gateway group') and specifies the resource and purpose ('for multi-WAN failover or load balancing'). This distinguishes it from sibling tools like search_gateway_groups, update_gateway_group, and delete_gateway_group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use the tool ('multi-WAN failover or load balancing'), which gives clear usage context. However, it does not explicitly mention alternatives or when not to use it, falling slightly 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, and the description adds 'irreversible,' which clarifies the permanence beyond the annotation. It doesn't mention confirm/dry_run safety gates, but those are documented in the schema, so the description adds useful context without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a concise warning. It is front-loaded with the action, and every word serves a purpose, making it extremely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with strong annotations and full schema coverage, the description is essentially complete. It lacks an explicit mention of confirm=true or dry_run=true, but those are in the schema, so the description does not need to repeat them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for auth_server_id, confirm, and dry_run. The description adds no additional parameter-specific meaning beyond the 'by ID' reference, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Delete a pfSense authentication server by ID.' This distinguishes it from sibling tools like create_auth_server, update_auth_server, and search_auth_servers, providing a specific verb, resource, and method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'delete' and the ID parameter, but there is no explicit when-to-use guidance or mention of alternatives such as update_auth_server for modifications. The description does not state how to obtain the auth_server_id or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds a strong 'irreversible' warning, which goes beyond the annotation. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The warning is front-loaded and the description 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, an output schema, and annotations, the description only needs to add extra behavioral context. The irreversibility warning covers that, making the tool sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents crl_id, confirm, and dry_run. The description adds no new parameter details beyond what's already in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with a clear resource (Certificate Revocation List) and scope (by ID). It clearly distinguishes this from sibling tools like create_crl or update_crl.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (delete when you have a CRL ID), but does not provide explicit when-to-use guidance or mention alternatives. The schema notes that the ID comes from search_crls, which is helpful context, but not part of the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint:true, so the destructive nature is known. The description adds the explicit warning that deletion is 'irreversible,' which is stronger and more specific than the destructive flag. This is valuable context about the permanence of the operation, though it does not mention confirm/dry_run parameters (covered in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the action is front-loaded, and the warning is concise. No filler or redundant content. It earns its place entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (all parameters documented), annotations (destructiveHint:true), and output schema, the description is sufficiently complete for the agent to select and invoke the tool. The irreversible warning adds essential context not fully captured by annotations. The confirmation workflow is documented in the schema, so the absence in the description is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% parameter documentation, including descriptions for job_id (referencing search_cron_jobs), confirm (safety gate), dry_run (preview), and apply_immediately. The description's phrase 'by ID' adds no new information beyond the schema. Baseline of 3 is appropriate when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the target resource ('cron job'), and the method ('by ID'). This unambiguously distinguishes it from sibling tools like search_cron_jobs and create_cron_job, as well as other delete_* tools targeting different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives or mention exclusions. Usage is implied (when you need to delete a cron job), but it lacks guidance such as using search_cron_jobs to obtain the ID or cautioning against use if temporary disablement is intended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description adds the specific warning 'This is irreversible,' which is a meaningful behavioral detail beyond the generic annotation. It does not contradict the annotations, and it alerts the agent to the permanence of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus a short warning. Every word earns its place, and the important irreversibility warning is prominently placed after the main statement. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, full parameter documentation, and annotations. The description covers the core purpose and adds the irreversible warning. It omits mention of the confirm safety gate, but that is clearly documented in the schema, so completeness remains high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with detailed descriptions for all four parameters (confirm, dry_run, pool_id, apply_immediately). The description itself adds no extra parameter meaning beyond reinforcing 'by ID,' so a baseline score of 3 is appropriate given the schema's thoroughness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the specific resource (DHCP address pool) plus the key qualifier (by ID). This distinguishes it from create/update/apply siblings, making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'by ID,' suggesting the caller must first obtain the ID (from search_dhcp_address_pools, as noted in the schema). However, it does not explicitly mention when to use this tool versus alternatives, nor does it state when not to use it, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true), and the description adds the crucial behavioral context that the deletion is irreversible, emphasizing the permanence of the action beyond the generic destructive flag. This adds useful warning information without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence with a clear action and an important warning. Every word earns its place, and the core purpose is front-loaded. No extraneous content or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with well-documented schema, annotations, and output schema. The description adds the critical 'irreversible' warning, and the parameter docs cover safety gates. It does not mention every step (e.g., searching for the ID first), but the overall context is adequate for a destructive single-entity deletion, and the existing structure covers most needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for all four parameters, including the safety gate (confirm) and dry_run option. The description itself adds no parameter-specific information beyond saying 'by ID', so it rests on the schema's strong coverage, which is the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with a specific resource ('DHCP custom option') and identifies the key identifier ('by ID'). This clearly distinguishes it from sibling tools like create_dhcp_custom_option, update_dhcp_custom_option, and search_dhcp_custom_options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for deleting a custom option, and the 'by ID' phrasing suggests the ID must come from a search, but it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites like retrieving the ID via search_dhcp_custom_options or the need for confirmation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a clear 'WARNING: This is irreversible' which goes beyond the destructiveHint annotation by emphasizing permanence. It does not mention safety gates like confirm or dry_run, but the annotations already signal the destructive nature, and the warning provides useful extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences: the first states the action and target, the second gives a critical warning. No filler or redundant phrasing; the structure is front-loaded and effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, annotations, and a schema covering all parameters, so the description does not need to explain return values or parameter formats. The only minor omission is the workflow for applying changes (e.g., apply_immediately), but the schema covers that. Overall the total definition is sufficient for understanding the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 four parameters. The description adds no additional parameter semantics beyond confirming the 'by ID' lookup, which is already in the override_id parameter description. It neither helps nor hinders beyond the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Delete') and resource ('DNS host override by ID'), clearly distinguishing it from related tools like delete_dns_domain_override or delete_dns_forwarder_host_override. The action and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by ID' phrasing implies the need to first search for the override identifier, but the description does not explicitly mention search_dns_host_overrides as a prerequisite or provide guidance on when to use this tool versus alternatives. No exclusions or workflow steps are given, making this minimal but not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the critical context that the deletion is irreversible, which goes beyond the annotation's generic destructive signal. This is valuable behavioral disclosure that helps the agent understand the consequence of invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and the key warning. Every word earns its place, and the irreversible warning is front-loaded. No unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation, the description, annotations, and schema together provide sufficient context: what is deleted, how to identify it, safety parameters (confirm, dry_run), and the irreversible warning. There is an output schema, so return values need not be described. It does not mention that the schedule_id should come from search_firewall_schedules, but that is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter including a description (e.g., schedule_id, confirm, dry_run, apply_immediately). The tool description adds minimal overlap by referencing 'by ID', but does not provide additional semantics beyond what the schema already offers. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the target resource ('firewall schedule'), and the required identifier ('by ID'). This distinguishes it from sibling delete operations like delete_firewall_rule and delete_schedule_time_range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when deleting a firewall schedule, but it does not explicitly state when to use it over alternatives or mention any prerequisites. The intent is clear from the name and description, so this is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds explicit irreversibility warning ('WARNING: This is irreversible'), which is valuable additional behavioral context beyond the annotation. It does not mention the confirm safety gate, but that is already documented in the parameter schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action, followed by a concise warning. It contains no filler and is appropriately sized for a destructive operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the detailed schema and annotations, the description is nearly complete. It conveys the core purpose and irreversibility. However, it does not explicitly mention the need to set confirm=true or that dry_run is available for preview, though these are in the schema. A bit more context could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all four parameters, including confirmation, dry run, client ID, and apply_immediately. The description only adds 'by ID', which aligns with client_id but no additional semantic value beyond the schema. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a FreeRADIUS client by ID.' It specifies the verb (delete), the resource (FreeRADIUS client), and the identifier method (by ID). This distinguishes it from sibling tools like search_freeradius_clients, create_freeradius_client, and update_freeradius_client.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (i.e., to delete a specific FreeRADIUS client) but does not explicitly state when to use it versus alternatives or mention prerequisites such as looking up the ID via search_freeradius_clients. It provides no exclusions or alternative tool recommendations, though the purpose is self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WARNING: This is irreversible,' which goes beyond the destructiveHint=true annotation by emphasizing permanence. This is useful context for the agent to make risk-aware decisions. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence plus a concise warning. It is front-loaded with the action and resource, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with an output schema and clear annotations, the description is nearly complete. It captures the essence (delete by ID, irreversible) and relies on the schema for parameter semantics. It does not mention that confirm must be true, but the schema explicitly covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters, including the meaning of group_id ('array index from search_groups'), confirm, and dry_run. The description adds no additional parameter-level detail beyond the schema, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the target resource ('pfSense user group'), and the identifier ('by ID'). It is specific and distinguishes this tool from sibling tools like update_group or search_groups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting a group, but does not explicitly mention when to use this tool over alternatives (e.g., update_group) or any prerequisites. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, and the description adds the crucial context that the deletion is 'irreversible.' This goes beyond the structured hint and is valuable for an agent deciding whether to proceed. It does not contradict annotations and provides additional risk information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action, the second delivers a warning. It is front-loaded and contains no filler, earning full marks for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete operation, the description covers the core purpose and warns of irreversibility. With detailed schema parameter descriptions and an output schema present, it does not need to explain return values. It could mention the confirm flag, but that is already in the schema, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with each parameter having a meaningful description. The tool description adds little beyond confirming backend_id is the target. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Delete an HAProxy backend by ID.' This clearly distinguishes it from sibling tools like delete_haproxy_frontend or search_haproxy_backends. It also specifies the identifier mechanism, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to remove a specific HAProxy backend, but it does not explicitly state when to choose this over alternatives or mention any prerequisites beyond the ID. The irreversibility warning serves as a caution but not a full usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds the qualitative warning 'irreversible' and clarifies that 'delete' means 'unassign', providing context beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the action and object, and includes a targeted warning. There is absolutely no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema documents confirm, dry_run, and apply_immediately, and an output schema exists, the description covers the essential behavioral semantics (irreversible, unassign). It could mention the apply workflow or the confirm requirement, but these are already fully documented in the schema, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 4 parameters with descriptions, including the confirm safety gate and apply_immediately. The description only references interface_id ('by ID') and adds no additional parameter semantics beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete (unassign)' and the resource 'interface', specifying deletion by ID. It distinguishes from sibling tools like delete_alias and update_interface by clearly identifying the object and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through its imperative verb, but it does not explicitly state when to use this tool versus alternatives like update_interface or other unassign methods. The warning about irreversibility implies caution but provides no alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as destructive, and the description adds the key nuance that deletion is irreversible, which is not captured by the readOnlyHint/destructiveHint flags. It does not detail side effects on dependent objects, but the safety value is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the action and resource, followed by a clear safety warning. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a detailed schema covering all parameters and annotations signaling destructiveness, the description is appropriately sized. The irreversible warning and ID requirement are the essential contextual additions. It could mention the need to set confirm=True, but that is adequately documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (phase2_id, confirm, dry_run, apply_immediately) already having explanatory descriptions. The tool description adds no additional parameter meaning beyond 'by ID', so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), the specific resource (IPsec Phase 2 / Child SA / tunnel), and the required identifier (by ID). This distinguishes it from related tools like update_ipsec_phase2 or search_ipsec_phase2s.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for removing an existing Phase 2 entry, but provides no explicit guidance on when to use this tool versus alternatives, prerequisites, or exclusions. The warning about irreversibility hints at caution but not at alternative workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds the specific warning 'WARNING: This is irreversible,' which goes beyond the annotation by disclosing permanence. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus a warning, front-loaded with the action and target. Every word earns its place with no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (confirm/dry_run/apply_immediately) and the destructiveHint annotation, the short description is mostly sufficient. It is slightly incomplete in that it does not mention the confirm gate or relationship to apply_ipsec_changes, but these are already covered by annotations, schema, and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents all four parameters with descriptions, including the confirm safety gate and dry_run behavior, so the description does not need to add parameter detail. The phrase 'by ID' reinforces encryption_id but adds no meaning beyond the schema's description. Baseline 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('IPsec Phase 2 encryption entry') with a clear mechanism ('by ID'), distinguishing it from sibling tools like search_ipsec_phase2_encryptions or update_ipsec_phase2_encryption. It exactly states the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage once an encryption_id is available and warns that deletion is irreversible, but it does not explicitly state when to prefer this over update_ipsec_phase2_encryption or how to obtain the ID. Usage context is clear but only implied, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds that deletion is irreversible, which is valuable behavioral context beyond the annotation. It does not describe the full deletion workflow (e.g., role of confirm/dry_run), but those details are present in the schema, and the warning is sufficient 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and includes an important warning. It contains no wasted words and does not redundantly repeat schema or annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema with safety gates (confirm, dry_run, apply_immediately) and the existence of an output schema, the description is adequate for a delete operation. The potential gap—explaining the need to apply changes if apply_immediately is false—is covered by the schema parameter description, so the description remains complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all four parameters, including the safety gate (confirm) and dry_run. The description itself adds no parameter-specific meaning beyond what the schema already states, so it meets the baseline for schema-covered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('outbound NAT mapping') with a clear identification method ('by ID'), distinguishing it from sibling search/create/update tools. The warning also clarifies the destructive scope, leaving no ambiguity about the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating 'Delete an outbound NAT mapping by ID,' but it does not explicitly discuss when to use this tool versus alternatives or mention exclusions. The sibling tool names (e.g., update_nat_outbound_mapping) provide indirect context, but no explicit guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WARNING: This is irreversible' which strengthens the destructiveHint annotation by conveying permanence and heightened caution. It does not contradict the annotations and provides behavioral context beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences. It is front-loaded with the action and includes a crucial warning, with no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructiveHint annotation, thorough schema descriptions, and presence of an output schema, the description is complete enough. It adds the key warning about irreversibility that is not captured in structured fields, making it sufficient for the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all four parameters (confirm, dry_run, queue_id, apply_immediately) well-documented. The description itself 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Delete a shaper queue by ID', using a specific verb and resource. It clearly identifies what the tool does and distinguishes it from sibling delete operations targeting other resources (e.g., delete_traffic_shaper).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance or alternatives. The phrase 'by ID' implies that users need to first obtain a queue ID, but no prerequisite like 'use search_shaper_queues first' is stated. Usage is implied by the tool's name and purpose rather than explicitly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, and the description adds 'WARNING: This is irreversible,' which meaningfully discloses the permanence of the action. This goes beyond the boolean annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and followed by a critical warning. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete tool with full schema coverage and an output schema, the description covers the essential purpose and risk. It could mention the need for confirm=True, but that is already documented in the schema, so it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all four parameters have descriptions. The tool description itself adds no parameter-specific meaning, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete), the resource (traffic limiter), and the identifier requirement (by ID). It distinguishes from sibling create/update/search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'Delete', but there is no explicit when-to-use guidance or mention of alternatives. The schema hints at using search_traffic_limiters for the ID, but the description itself lacks that context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds an 'irreversible' warning, which is useful but does not disclose potential side effects like impact on firewall rules or the need for applying changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a warning, front-loaded with the action and resource. It is concise and free of unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and annotations, the description is nearly complete. It could mention confirmation requirements or checking for references, but those are available in the schema. The irreversible warning adds needed context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all parameters. The description itself adds no additional parameter semantics, but this is acceptable since the schema handles it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), the resource (virtual IP), and the identifying method (by ID). It naturally distinguishes itself from sibling tools like create_virtual_ip and update_virtual_ip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for deleting a virtual IP. It does not explicitly state when to use it over alternatives or mention exclusions, but the purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral detail by specifying the exact checks performed (ping, ARP lookup, gateway status) and that it produces a combined diagnosis. This goes beyond simple read-only declaration and helps the agent predict what happens.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the primary purpose. Every sentence earns its place by describing scope and method without verbose detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values need not be described. Annotations cover safety, and the description explains inputs and behavior sufficiently. A small deduction for not providing any direct comparison to similar diagnostic sibling tools, but the description is otherwise complete for a simple diagnostic operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already clearly explains 'host' and 'count' including defaults and max. The description adds little beyond the schema except that ping is involved, which is already implied by the count parameter. Baseline 3 is appropriate since the schema carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Test connectivity') and clearly identifies the resource and scope: a host from the pfSense appliance. It differentiates itself by listing the combined checks (ping, ARP, gateway) that produce a diagnosis, distinguishing it from simpler sibling tools like run_ping_diagnostic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'combined connectivity diagnosis' and lists the components, but it does not explicitly state when to prefer this over run_ping_diagnostic, get_arp_table, or get_gateway_status. No when-not-to-use or alternative guidance is included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe read-only operation. The description adds behavioral context by enumerating the checks (interface status, configuration, gateway status, ARP entries), which clarifies the tool's diagnostic scope beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and purpose, and contains no fluff or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only diagnostic tool with an output schema, the description sufficiently conveys what the tool does and when to use it. It could optionally reference related tools, but the current level of detail is adequate given the simplicity and existing structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'interface' is fully documented in the schema with a description and example values. The tool description adds no additional parameter-level detail, but schema coverage is 100%, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Analyze') and resource ('interface'), then details the four specific checks performed. This clearly distinguishes it from sibling diagnostic tools like diagnose_vpn_status or get_gateway_status by focusing on interface-level health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for troubleshooting interface problems but does not explicitly state when to prefer this tool over alternatives such as get_gateway_status or get_arp_table. There is no mention of exclusions or scenarios where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=false and destructiveHint=false, offering little safety context. The description adds 'Generates downloadable client configuration,' which clarifies the output but does not disclose side effects, permissions, or rate limits. It is not contradictory but provides minimal additional behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise, with the action verb 'Export' in the first sentence and a brief clarifying sentence. Every word contributes to understanding the tool's purpose, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description does not need to explain return values. The description provides sufficient high-level context for a tool with many optional parameters, and the mention of both config file and installer package covers the key variation. It could have been slightly more explicit about the downloadable nature, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so each of the 13 parameters is described in the input schema. The description does not add extra semantic detail about parameters, interactions, or the importance of server_id, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'Export' and the resource 'OpenVPN client configuration file or installer package,' which distinguishes it from sibling tools like search_openvpn_client_export_configs that list existing configs. The added sentence about generating downloadable client configuration reinforces the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for generating a new client configuration or installer package for a pfSense OpenVPN server. However, it does not explicitly mention when not to use it or refer to alternatives (e.g., search_openvpn_client_export_configs), so it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful context that entries reflect recently communicated devices and include non-DHCP devices, but it does not disclose details about pagination, data freshness, or potential empty results. This is adequate given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with no extraneous information. The purpose is front-loaded in the first sentence, and the second adds valuable scope clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with an output schema and strong annotations, the description sufficiently conveys purpose, scope, and intended use. It could slightly improve by noting that ARP entries are ephemeral, but 'recently communicated' already implies this. Complete enough for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are fully described in the input schema (100% coverage), and the description does not add any additional parameter-specific details. It only mentions IP-to-MAC mappings, which broadly relates to ip_address and mac_address filters. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with resource 'ARP table' and states its purpose ('to discover devices on the network'). It also clarifies the data included (IP-to-MAC mappings, including non-static DHCP devices), which distinguishes it from potential sibling tools like search_dhcp_leases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'to discover devices on the network' provides clear context for when to use this tool. However, it does not explicitly state when not to use it or mention alternative tools (e.g., search_dhcp_leases) for static mappings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scoping detail that only unassigned interfaces are returned. It does not disclose additional behavior such as sorting, filtering, or data structure, but this is acceptable given annotations and the tool's simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of nine words, with the main action and resource front-loaded. There is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, read-only, output schema present), the description is sufficient. It communicates the essential scope of 'unassigned' interfaces, and the existing output schema handles return value details. A slightly richer statement about when to use it would improve completeness, but it is not strictly necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema confirms this with 100% coverage. Per the baseline for zero-parameter tools, a score of 4 is appropriate. The description adds no parameter details because none exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'list of available (unassigned) network interfaces', making the tool's purpose explicit. The parenthetical 'unassigned' differentiates it from sibling tools like search_interfaces or find_interfaces_by_status, which likely cover broader or different interface queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives is provided. The description implies usage when unassigned interfaces are needed, but it does not name alternatives or state exclusions, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns status for 'all' clients, but it does not detail what status fields are included or whether the data is real-time. This is adequate but not rich behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that immediately conveys the tool's purpose. Every word earns its place; no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only status tool with an output schema, the description is complete enough for basic selection. However, it lacks any distinction from related status tools (e.g., get_openvpn_status) and offers no usage context, making it slightly incomplete for nuanced agent decisions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is trivially 100%. With no parameters, the baseline is 4; the description correctly implies no filtering is possible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the status of all OpenVPN clients' uses a specific verb 'get' and clearly identifies the resource ('status of all OpenVPN clients'), distinguishing it from siblings like get_openvpn_server_status and get_openvpn_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing client status, but it provides no explicit guidance on when to prefer this tool over alternatives such as get_openvpn_server_status or search_openvpn_server_connections. No exclusions or alternative mentions are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the annotations by mentioning the ACME challenge/validation process, implying external interaction and potential delay. It does not contradict the annotations (write operation, idempotent, non-destructive). It could further disclose rate limits or prerequisite conditions, but the added process detail is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and the second sentence adds a meaningful detail. No wasted words or repetition of schema/annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema and annotations, the description is reasonably complete. It explains the ACME process and the schema provides the ID source. However, it does not mention prerequisites like needing an ACME account key or that the certificate must already be configured, which could be useful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter 'id', which already explains the source ('from search_acme_certificates'). The tool description itself adds no additional parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Issue') and resource ('ACME certificate from Let's Encrypt'). It distinguishes from sibling tools like create_acme_certificate (creating the entry) and renew_acme_certificate (renewing) by focusing on obtaining the certificate via the ACME challenge.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to obtain an ACME certificate) but does not explicitly distinguish from alternatives. It doesn't state 'use this for initial issuance, not renewal' or mention that the certificate must already exist as an ACME certificate. The context is clear but lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds 'triggers the renewal process,' hinting at an action that may involve external ACME interactions, but it doesn't expand on side effects, asynchronous behavior, or failure states. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. The purpose is stated immediately, and the second sentence reinforces the action without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, 100% schema coverage, output schema present, annotations provided), the description is largely sufficient. The only meaningful gap is lack of explicit differentiation from the sibling 'renew_certificate,' but the name itself conveys the ACME specificity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides complete coverage for the single parameter (id) with description 'Certificate ID to renew (from search_acme_certificates).' The tool description adds no additional parameter semantics beyond what the schema states, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Renew an existing ACME certificate' and 'Triggers the renewal process for a previously issued certificate.' This distinguishes it from the sibling 'renew_certificate' (generic) and 'issue_acme_certificate' (initial issuance vs renewal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It establishes clear context: renewal is for previously issued certificates, implying it's not for new issuances. However, it doesn't explicitly mention alternatives or when to use another tool (e.g., renew_certificate for non-ACME certs). It also doesn't state any prerequisites or caveats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds the behavioral context of supporting filtering and pagination. It clarifies the resource scope as active connections without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core purpose, no redundant words. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with an output schema and comprehensive annotations, the description covers the essential aspects. The schema explains parameters and output, so the description doesn't need to elaborate further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully documented in the schema. The description's mention of 'filtering and pagination' maps to search_term and page/page_size but adds no new meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the resource (firewall states/active connections) and action (search), with explicit mention of filtering and pagination. This distinguishes it from siblings like search_firewall_rules and delete_firewall_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for querying the state table with optional filters and paging, but does not explicitly state when to prefer this over alternatives or mention exclusions. No alternative tools are referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clearly covered. The description adds behavioral details about filtering and pagination, but does not elaborate on return structure or search semantics, which is acceptable given the 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently states the purpose and core features without redundancy. Every word contributes value, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With read-only annotations, full schema coverage, and an output schema present, the description is sufficiently complete for a search tool. It could be more explicit about return values or edge cases, but these are not necessary given the structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full descriptions for all four parameters (page, sort_by, page_size, search_term), covering 100% of the parameter semantics. The description does not add parameter-level detail beyond summarizing filtering and pagination, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (Search), the resource (FreeRADIUS clients/NAS devices), and key capabilities (filtering and pagination). This clearly distinguishes it from sibling tools like search_freeradius_users by naming the specific resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear resource context and implies this tool is for querying FreeRADIUS client objects, differentiating it from create/update/delete client tools. It does not explicitly name alternative tools or state when not to use it, but the resource specificity and read-only annotation offer sufficient guidance for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only behavior is covered. The description adds the prerequisite that the FreeRADIUS package must be installed, which is useful context about potential failure. It does not add other behavioral details like error conditions or side effects, but given the annotations, the bar is lower.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action ('Search FreeRADIUS users'). The second sentence about the package prerequisite is valuable and concise. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high schema coverage, presence of an output schema, and annotations, the description provides enough context to invoke the tool. It adds the prerequisite about the FreeRADIUS package, which is an important operational detail. It does not explicitly discuss sibling alternatives, but the tool name and schema descriptions largely fill that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all four parameters (page, sort_by, page_size, search_term) having descriptions. The description does not add additional semantics beyond the schema; 'filtering and pagination' merely summarizes the parameter descriptions. Baseline 3 is appropriate because the schema already does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and resource 'FreeRADIUS users', making its purpose immediately clear. It distinguishes itself from sibling tools like create_freeradius_user and search_freeradius_clients by naming the exact resource and action. Mentioning 'filtering and pagination' further clarifies the tool's scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that the FreeRADIUS package must be installed, which is a prerequisite for using the tool. It does not explicitly name alternatives or state when not to use this tool, but the resource name and sibling context make the intended use obvious. The prerequisite is a useful usage hint that goes beyond simple function naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds no extra behavioral context beyond the basic purpose. It doesn't disclose return format, response size, or rate limits, but these are less critical given the annotations and output schema presence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-formed sentence that conveys the essential purpose without waste. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only search with full schema documentation and an output schema, so the description is sufficient for basic invocation. However, it could have added a brief note about what a 'gateway' represents or that it returns all gateways if no filters are applied. Still, it is complete enough given the available structured context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed descriptions for all six parameters, including defaults and examples. The description itself only mentions 'filtering and pagination' which aligns with the parameters but doesn't add any meaning 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('routing gateways') and mentions filtering and pagination. This clearly distinguishes it from sibling tools like get_gateway_status (status lookup) and search_gateway_groups (gateway groups).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies use for listing/searching gateways with filtering options, but it does not explicitly name alternatives or state when not to use it. Context is clear enough for an agent to infer this is the general search tool for gateways.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds the specific scope of listing bind addresses, but does not elaborate on pagination behavior or the format of addresses; the output schema likely covers these details. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, completely clear sentence with no filler or redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with pagination parameters, a complete output schema, and annotations, the description is sufficient. It could explicitly mention pagination behavior, but the schema and annotations fill the remaining context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter is documented, including parent_id's origin and page/page_size defaults. The description adds no further parameter semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and names the resource 'bind addresses configured on an HAProxy frontend', clearly distinguishing this tool from sibling tools like search_haproxy_frontends (which lists frontends) and manage_haproxy_frontend_address (which manages addresses).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly discuss alternatives, but the parent_id parameter description instructs the agent to obtain the frontend ID from search_haproxy_frontends, conveying a clear workflow context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that filtering and pagination are supported, providing some behavioral context beyond a simple list, but does not detail response format or other traits. This meets the baseline for annotated read-only tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no superfluous words. It effectively communicates the core function and key features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity search tool with complete parameter schema, an output schema, and appropriate annotations, the description is sufficient. It could specify what 'installed packages' refers to (e.g., OS packages) but this is not critical given the tool name and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of all 4 parameters with descriptions. The description's mention of 'filtering' and 'pagination' maps to search_term and page/page_size, but does not add meaning beyond what the schema already states. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Search') and resource ('installed packages'), and adds 'filtering and pagination' to define scope. It distinguishes from sibling search_* tools by targeting a unique resource not covered elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding installed packages with optional filtering/pagination, which is clear context. It does not explicitly mention when not to use or name alternatives, but no other sibling targets packages, so this is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scoping behavior ('within a firewall schedule') but does not disclose pagination, client-side filtering, or sort behavior; these are instead covered in the schema descriptions. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately states the action and resource, making it easy to parse and remember.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has comprehensive schema descriptions, annotations, and an output schema, so the minimal description is mostly sufficient. It could explicitly mention that it lists time ranges for a given schedule, but the name, description, and required parent_id already make that clear. The output schema likely covers return values, so no additional description is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all five parameters already have meaningful descriptions. The tool description itself adds no parameter-level detail. The schema covers parent_id, search_term, pagination, and sort fields adequately, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' and identifies the resource as 'time ranges within a firewall schedule'. This clearly distinguishes it from sibling tools like create_schedule_time_range or search_firewall_schedules, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the scope ('within a firewall schedule'), implying the need for a parent schedule ID. The schema's parent_id description ('from search_firewall_schedules') reinforces the prerequisite, but the description itself does not explicitly name alternatives or exclusion conditions. This is clear context but lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the tool supports filtering and pagination, which is useful behavioral context, but it does not disclose details like result ordering or any server-side limitations beyond what the schema implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the primary action and resource. Every word contributes meaning: 'Search' indicates the verb, 'traffic shaper queues' the resource, and 'filtering and pagination' the key behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with a full input schema, annotations, and an output schema, the description sufficiently covers the core purpose. It does not explain return values, but the output schema covers that. It could mention whether any filters are mutually exclusive, but that is not necessary for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with descriptions for all four parameters, so the description does not need to explain them. The phrase 'filtering and pagination' generically aligns with the search_term and pagination parameters, but does not add any detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search traffic shaper queues with filtering and pagination' clearly identifies the verb (Search), the resource (traffic shaper queues), and distinguishes this tool from sibling search tools like search_traffic_shapers by specifically targeting queues. The mention of filtering and pagination adds useful scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: when you need to find or list traffic shaper queues. It gives clear context but does not explicitly state when not to use it or mention alternative tools, so it falls 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context by mentioning filtering and pagination, which indicates the tool returns a subset of results in pages. This is useful beyond the annotations, though it doesn't detail sorting or client-side filter behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and resource. Every word is essential, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple search nature, an output schema exists, annotations cover safety, and all parameters are documented in the schema, the description is nearly complete. It could explicitly state that results are lists or that it's read-only, but such details are implied by annotations and the output schema, leaving minimal gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds minimal parameter-specific meaning beyond mentioning 'filtering and pagination'; it does not elaborate on which fields are filterable or how pagination works, relying on the schema for details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' with a clear resource 'static routes' and adds scope 'with filtering and pagination'. This distinguishes it from other search tools like search_crls or search_ntp_time_servers, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for querying static routes but does not explicitly state when to use it versus alternatives (e.g., get_gateway_status for gateway health, or search_gateways for gateway configuration). No exclusion criteria or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as mutating (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description simply restates the update verb without adding extra context such as partial-update semantics, error behavior for missing IDs, or the need to fetch the ID via search_auth_servers. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise sentence that directly states the purpose. No filler or redundancy. It is appropriately sized for a simple update operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with the fully described input schema and the presence of an output schema, the description is sufficient for an agent to understand the tool's basic function. It lacks explicit partial-update semantics, but the optional parameters with null defaults in the schema compensate for that gap. Given the rich schema and annotations, the description is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 19 parameters already have detailed descriptions. The tool description itself provides no additional parameter guidance, which is acceptable per the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (authentication server), and the scope (by ID). It distinguishes itself from siblings like create_auth_server, search_auth_servers, and delete_auth_server by explicitly indicating an existing server update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: modify an already existing auth server identified by its ID. It does not explicitly mention alternatives or when not to use it, but the context is unambiguous given the tool name and the 'by ID' qualifier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate the tool is mutating (readOnlyHint=false, destructiveHint=false). The description adds meaningful context by warning that stopping critical services (dhcpd, unbound, sshd) will disrupt network operations, which is not conveyed by the annotations. It does not discuss permission requirements, but the specific safety warning adds value beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences: one for the tool's purpose and one for a critical safety warning. The warning is not boilerplate; it names specific services and the consequence of stopping them, earning its place. No unnecessary repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter schema, clear annotations, and presence of an output schema, the description sufficiently covers the tool's behavior. It states the operation, the target resource, and the key risk (disruption of network operations). There are no significant gaps for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with descriptions and examples (service_name, action). The description's warning adds an extra service example ('sshd') but otherwise does not elaborate on parameter semantics. With 100% schema description coverage, the description contributes little beyond the schema, meriting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Start, stop, or restart a service on the live pfSense appliance.' This provides a specific verb (start/stop/restart), resource (service), and scope (live appliance), clearly distinguishing it from read-only sibling tools like search_services.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need to change a service's state but does not explicitly contrast it with alternative tools such as search_services for listing services. The warning about critical services gives cautionary context but no explicit guidance on when not to use the tool. Thus usage is implied rather than explicitly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WARNING: This is irreversible,' which goes beyond the destructiveHint annotation by explicitly stating the permanence of the action. It also specifies that the target is an 'ACME certificate entry,' clarifying what gets destroyed. This is useful context beyond the structured annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with the verb and resource front-loaded, followed by a concise, high-impact warning. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives the essential purpose and irreversibility warning, but doesn't highlight the confirm parameter required for execution or the dry_run preview option. These are present in the schema, but for a destructive tool, the description could guide the agent to set confirm=true. The output schema and annotations fill some gaps, so completeness is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds minimal parameter semantics beyond the schema—only 'by ID' which corresponds to the certificate_id property already described in the schema. No additional meaning is provided for confirm, dry_run, or apply_immediately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes an ACME certificate entry by ID, using a specific verb and resource. It distinguishes from general certificate deletion (delete_certificate) and other ACME operations like create, update, issue, or renew.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys the operation's scope: deleting an ACME certificate by ID. While it doesn't explicitly list alternatives or exclusions, the 'by ID' phrasing implies the prior use of search_acme_certificates, which is standard for such tools. No misleading or irrelevant guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint=true), and the description adds the stronger context that the operation is 'irreversible'. This goes beyond the annotation by emphasizing permanence, which is valuable for a delete operation. However, it doesn't describe the confirm/dry_run workflow in the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the warning front-loaded. No unnecessary words, making it very easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple destructive operation, the schema's clear safety-gate parameters (confirm, dry_run), and an output schema, the description covers the essential context. The irreversibility warning and ID reference are sufficient for an agent to understand the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters including confirm and dry_run. The description adds no additional param semantics beyond 'by ID', which is already clear from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Delete a certificate by ID', using a specific verb and resource, clearly distinguishing it from sibling tools like delete_certificate_authority or delete_crl. The identifier detail adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are provided. The irreversibility warning implies caution, but the description doesn't suggest using search_certificates first or leveraging the dry_run/confirm parameters. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds the context that deletion is irreversible, which goes beyond the annotation. It also implies the target is a time range within a schedule, clarifying what is destroyed. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a warning. It is front-loaded with the action and resource, and every word adds value. The warning is prominent and appropriately placed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% param coverage), annotations (destructiveHint=true), and output schema, the description is complete for a single-purpose delete tool. It covers the essential information (what is deleted and irreversibility) while leaving operational details to the schema. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds only 'by ID' reference, which aligns with time_range_id but does not add additional meaning beyond the schema. The schema already documents confirm, dry_run, and apply_immediately sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('a time range from a firewall schedule') with the method ('by ID'). It clearly distinguishes from sibling tools like delete_firewall_schedule by specifying the scope as a single time range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (delete a specific time range by ID) but does not explicitly mention alternatives or exclusions. For example, it does not state 'To delete an entire schedule, use delete_firewall_schedule instead.' The usage context is clear from the tool name but not elaborated with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds only the qualifier 'current' which hints at a live snapshot, and expands the acronym, but does not disclose response behavior, permissions, or other operational details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and contains no filler. It effectively conveys the tool's purpose in minimal words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no nested objects, output schema present) and the read-safe annotations, the description covers the essential purpose. The output schema handles return value details, so no additional explanation is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema fully documents the input surface. The description adds no parameter information, but none is needed; per the baseline for zero-parameter tools, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and names the exact resource 'CARP (Common Address Redundancy Protocol) status', expanding the acronym for clarity. This distinguishes it from sibling status tools like get_gateway_status by naming a distinct protocol.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via its resource name but provides no explicit guidance on when to choose this tool over alternatives like get_gateway_status or get_openvpn_status. For a simple getter, the intended use is self-evident, but it lacks any exclusions or situational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only safety profile is covered. The description adds little beyond the resource name; no additional behavioral traits like error handling or response format are described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that is front-loaded with the verb and resource. No fluff, exactly as much as needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple get operation with one parameter, strong annotations, and an output schema. The description is complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already explains revision_id comes from get_config_history. The tool description adds no parameter semantics, but the schema carries the burden sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a specific configuration history revision by ID. It distinguishes from siblings like get_config_history (which lists revisions) and compare_config_revisions (which compares them).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call this when you need a single revision by ID. It doesn't explicitly exclude alternatives or name sibling tools, but the context is clear enough with the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is consistent and adds no additional behavioral context. It does not explain response format, permissions, or any special behavior beyond the act of fetching settings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of six words. It is front-loaded with the action and resource, containing no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only getter, this description is fully sufficient. An output schema exists, so return values are already documented. The simplicity of the tool requires no additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema documents this fully. The description correctly avoids parameter details because none exist; baseline score of 4 for no-parameter tools applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and names the exact resource 'DHCP relay settings.' This clearly distinguishes it from sibling tools like get_dhcp_server_config and update_dhcp_relay_settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the getter pattern and tool name, but the description gives no explicit when-to-use or alternative exclusions. For a simple read-only getter, this is minimally acceptable, yet it does not differentiate from other 'get_*' settings tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the 'real-time' aspect and specific metrics, but no further behavioral detail such as error handling or data freshness. This meets the baseline for a safe read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that fronts the verb and packs the necessary information without filler. It is appropriately sized and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and no parameters, the description supplies sufficient information for an agent to invoke the tool correctly. It clearly states what status values are returned, making the tool's behavior predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is fully covered. Per instructions, a 0-parameter tool receives a baseline score of 4; the description correctly avoids adding unnecessary parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and identifies the resource ('gateway status') with concrete indicators (latency, packet loss, online/offline state). This clearly distinguishes it from configuration-focused siblings like get_default_gateway or search_gateways.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. The real-time monitoring context implies its use for status checks, but it does not name sibling tools or describe when not to use it, leaving usage to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds context about the settings included (protocol, port, certificates) but does not disclose any additional behavioral traits such as permissions, rate limits, or side effects beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and every word adds value. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema available, and read-only annotations, the description sufficiently covers the tool's purpose and basic expectations. It is complete for this simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema is empty. The description correctly does not need to explain parameters; the baseline score of 4 applies for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and resource 'WebGUI settings', with examples (protocol, port, certificates) that clarify the scope. It clearly distinguishes from sibling get_* tools for other subsystems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or alternative tools. Usage is implied by the name and description, but no guidance is provided beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context that the ping originates from the pfSense firewall, which is a meaningful behavioral detail not captured by annotations or schema. For a simple read-only diagnostic, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no redundant wording. It conveys the essential purpose in under ten words, making it easy to parse and remember.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with clear annotations, a complete input schema, and an output schema present. The description plus structured data fully cover what the tool does and where it operates, leaving no critical gaps for a diagnostic action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both 'host' and 'count' described. The description itself adds no parameter information, but the schema fully documents the parameters, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool runs a ping diagnostic from the pfSense firewall, using a specific verb ('run') and resource ('ping diagnostic'). It distinguishes itself from broader diagnostic siblings like diagnose_connectivity by focusing on a specific operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for testing network reachability but provides no explicit when-to-use or alternative comparisons. It does not mention that this is a targeted ping as opposed to a broader connectivity diagnostic, leaving the agent to infer its role among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no behavioral details beyond restating the tool's purpose; it does not mention pagination behavior, filtering semantics, or any prerequisites. This is a minimal but non-contradictory disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the action and resource. Every word contributes value, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read-only search with one required parameter (parent_id) and a well-documented schema. An output schema exists to describe return values, and annotations cover safety. The description, while minimal, is sufficient given the richness of the structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting all six parameters including their defaults and types. The description adds no additional parameter context, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'search' and identifies the resource as DNS records within a BIND zone, clearly distinguishing from sibling tools like search_bind_zones (which lists zones) and manage_bind_zone_record (which modifies records).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear context for a read-only search operation, but it does not explicitly mention when to use it over alternatives such as search_bind_zones or manage_bind_zone_record. No exclusions or alternative recommendations are provided, but the purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the tool supports filtering and pagination, which is consistent with the schema, but does not disclose return format or other behavioral details beyond that. It explains what CSOs are, which is contextually useful but not behavioral.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with the first sentence stating the tool's purpose and the second providing useful background on CSOs. There is no redundancy or filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple search operation with annotations indicating it is read-only and non-destructive. The schema fully documents all parameters and an output schema exists, so the description, while brief, is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the 6 parameters already described. The description mentions filtering and pagination generically but adds no specific parameter semantics 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Search OpenVPN Client Specific Overrides (CSOs) with filtering and pagination,' naming the exact action and resource. It clearly distinguishes this tool from siblings like manage_openvpn_cso and search_openvpn_servers by focusing on CSO search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool—whenever you need to search or list OpenVPN CSOs—by explicitly stating its purpose. It does not mention alternatives or exclusions, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds minor context by clarifying that tunables are sysctl values, but discloses no additional behavioral traits like authentication needs or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the core action and resource. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full param descriptions, an output schema, and clear annotations, the description is sufficient. It also adds helpful context that system tunables are sysctl values, which aids agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter already has a description. The description's mention of 'filtering and pagination' adds no additional meaning beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and the resource ('system tunables (sysctl values)'), which precisely defines the tool's purpose. It also adds 'filtering and pagination' to distinguish this search tool from mutation siblings like create/update/delete_system_tunable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a read-only search tool, and sibling tools for modifications are clearly separate. However, it does not explicitly state when to use this vs alternatives or list any exclusions, so it falls 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds minimal behavioral context (filtering, pagination) but not deep details like response handling or edge cases. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the action and key features (filtering, pagination) efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema, annotations, and presence of an output schema, the description is sufficiently complete. The agent has all necessary structured context, and the description clearly frames the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already described clearly (page, sort_by, page_size, search_term). The description adds no new parameter-level meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' with a clear resource 'VLANs' and adds scope 'with filtering and pagination'. It clearly distinguishes from create/update/delete VLAN siblings and other resource-specific search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for searching/filtering VLANs with pagination. It doesn't explicitly list alternatives or exclusions, but the resource-specific name and parameters make when-to-use unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds 'filtering and pagination' as behavioral traits, but these are already reflected in the input schema parameters (page, page_size, peer_id, sort_by). Since the description repeats what the schema already communicates without adding deeper context (e.g., default sorting, result limits, or relationship to peer entities), it provides minimal additional behavioral disclosure beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that fully conveys the tool's purpose without unnecessary words or repetition. Every word earns its place, and the structure is highly compact and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward read-only search operation with an output schema and full parameter documentation. The description combined with the structured data (annotations and input schema) provides all necessary information for an agent to select and invoke the tool correctly. No additional return-value explanation is needed because the output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all four parameters, each with clear descriptions. The description's mention of 'filtering and pagination' summarizes the parameter behavior but does not add meaning beyond the schema. The schema itself provides all necessary parameter semantics, so the description adds no extra value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search WireGuard peer allowed IPs with filtering and pagination' uses a specific action verb ('Search') and clearly identifies the resource ('WireGuard peer allowed IPs'). It distinguishes itself from sibling tools like search_wireguard_peers, which targets the peers themselves, and manage_wireguard_peer_allowed_ip, which manages individual allowed IPs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the tool's context as a search/filter operation for allowed IPs. While it does not explicitly mention alternatives or exclusions, the resource is unique enough that no ambiguity exists about when to use it versus other WireGuard tools. The readOnlyHint annotation reinforces that this is a safe read operation, but the description itself offers no additional guidance on when to choose it over similar search tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds 'with filtering and pagination', which is a behavioral trait but is also fully evident from the input schema (page, page_size, enabled, search_description). No additional context such as default sorting, limits, or edge cases is provided. This is acceptable but not additive beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core action ('Search WireGuard tunnels') and immediately adds the key modifiers ('with filtering and pagination'). There is zero redundancy or irrelevant detail, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich input schema (100% coverage with detailed parameter descriptions), strong annotations (read-only, non-destructive), and the presence of an output schema, the description is sufficient. It clearly names the resource and operations, and the structured data fills in all necessary details such as parameters, defaults, and return structure. No additional description is needed for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (page, enabled, sort_by, page_size, search_description) having a meaningful description. The tool description does not add any parameter-specific detail beyond the generic 'filtering and pagination', which is already captured in the schema. Baseline 3 is appropriate since the schema carries the full semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search WireGuard tunnels with filtering and pagination' uses a specific verb ('Search') and resource ('WireGuard tunnels'), clearly distinguishing it from sibling tools like search_wireguard_peers and search_wireguard_tunnel_addresses. It also highlights key features (filtering, pagination), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when needing to search/list WireGuard tunnels with optional filtering and pagination. It does not explicitly name alternatives or exclusions, but the context is clear and intuitive given the tool name and sibling tools. The absence of exclusions or explicit alternative references prevents a 5, but the purpose is straightforward enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the behavioral detail that the status includes CPU, memory, disk, and version, but it does not mention any additional behavioral traits like caching, freshness, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that states the action and the scope of the result. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only status tool, the description is complete: it tells the agent what the tool does and what metrics are included. The presence of an output schema removes the need to describe return values, and the annotations cover safety behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline is 4. The description correctly implies that no input is needed, and there is no parameter semantic burden to add beyond what the empty schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource as 'current system status' with concrete details: CPU, memory, disk usage, and version info. It is distinct from sibling tools like get_system_hostname or get_system_version, as it provides a broad status snapshot rather than a single attribute.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for checking overall system health and resource usage, but it does not explicitly state when to use this versus alternatives such as get_system_health_report or get_system_version. No exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds the concept of pending changes and batch activation, which is useful, but it doesn't elaborate on system effects, service restarts, or any potential side effects. It satisfies the baseline but doesn't add rich behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, and zero padding. Every word earns its place, making it very concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter apply-style tool with annotations and an output schema, the description covers the essential trigger condition and outcome. It doesn't explicitly exclude non-IPsec changes, but the name and scope make that unambiguous. Slightly more context (e.g., whether it applies all pending changes across modules) would elevate it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description has no parameter burden. The description correctly doesn't invent parameter details, and with 100% schema coverage, the baseline for zero parameters applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('apply') and resource ('pending IPsec configuration changes'), clearly distinguishing it from other apply_*_changes tools by scope. It also clarifies the activation mechanism (pending changes with apply_immediately=False), leaving no doubt about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: after making IPsec changes with apply_immediately=False, to activate them all at once. This provides clear context, though it does not explicitly name alternative apply_* tools or state when not to use it, so it doesn't reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey idempotency and non-destructiveness. The description adds that it batches pending changes and shares the firewall apply endpoint, which is useful context but doesn't elaborate on potential side effects or endpoint behavior. It adds some value beyond the annotations but lacks depth, so a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly packed sentences: the purpose and the usage context, plus a note about the shared endpoint. It is front-loaded with the essential action, and every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter apply tool with an output schema and good annotations, this description covers the core purpose, when to use it, and a relevant technical detail. It doesn't mention edge cases like no pending changes or potential errors, but given the tool's simplicity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the schema description coverage is effectively 100% (vacuously). Per rubric, a zero-parameter tool receives a baseline of 4, and the description doesn't need to explain params. It adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Apply) and resource (pending NAT changes), with the parenthetical 'outbound mappings, mode changes' narrowing the scope. This clearly distinguishes it from sibling tool apply_nat_onetoone_changes, which handles one-to-one NAT. The action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance: 'Use this after making changes with apply_immediately=False to batch-apply them.' This sets a clear precondition. However, it does not explicitly mention alternatives or when-not-to-use cases, only implying scope via the parenthetical, so it stops 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds the context that it applies pending changes related to apply_immediately=False, which is useful. However, it does not disclose any potential side effects or outcomes beyond what is implied, and with annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, highly concise, and front-loaded with the core purpose. The second sentence adds crucial usage guidance without any fluff, earning a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter batch-apply tool, the description covers the essential purpose and usage trigger. It does not describe the output format, but the presence of an output schema likely covers that. It also does not list prerequisites beyond apply_immediately=False, which is the key one. Overall, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
This tool has no parameters, so the schema provides no content to elaborate on. The description does not need to add parameter meaning, and the baseline for zero parameters is 4. It correctly omits irrelevant parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Apply pending virtual IP changes.' It clearly distinguishes from other apply_* tools by specifying the virtual IP domain, and the pending aspect adds clarity. The second sentence further clarifies the operation is for batch-applying changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Use this after making changes with apply_immediately=False to batch-apply them.' This provides clear context, though it does not mention alternatives or explicitly say when not to use it. For a simple apply tool, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a mutating but not destructive operation. The description adds behavioral context beyond annotations by revealing that import and internal generation route to different API endpoints, which is important for understanding why the 'method' parameter exists and how the tool behaves internally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: a clear purpose statement and a useful implementation note. It is front-loaded with the core action and contains no filler or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters) and the presence of an output schema, the description is appropriately minimal. The schema documents every parameter and their conditional requirements, so the description does not need to reproduce that. The routing note adds valuable context for a dual-mode operation. The only minor gap is not explicitly stating which parameters are required for import vs. generation, but the schema covers this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, with all 14 parameters having meaningful descriptions (e.g., 'required for import', 'required for ECDSA generation'). The description only adds a note about routing on 'method', which is partially redundant with the schema's method description. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Create or import a Certificate Authority on pfSense'. This clearly distinguishes it from sibling tools like create_certificate (which creates certificates, not CAs) and update_certificate_authority (which modifies existing CAs). It also accurately reflects the dual modes of operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to create a new CA or import an existing one. The sentence 'Import and internal generation use different API endpoints; this routes on method' implicitly explains that the 'method' parameter selects the use case. It does not explicitly list exclusions or alternatives, but given there is no sibling tool for creating a CA, this lack is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations report readOnlyHint=false and destructiveHint=false, providing no safety profile. The description adds a meaningful constraint (API requires at least one time range), but does not disclose other behavioral aspects like apply_immediately semantics, validation errors, or the relationship between initial and subsequent ranges. It provides some context beyond annotations but not rich detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose, and provides a key constraint plus an alternative in a compact form. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema (100% parameter coverage) and output schema, the description covers the essential creation constraint (initial time range required) and points to the sibling for extending ranges. It stops short of explaining all edge cases, but is sufficient for a create tool with such detailed structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 9 parameters completely. The description adds minimal parameter-level meaning, only mentioning the 'initial time range' concept which maps to the hour parameter already documented in the schema. No additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 ('firewall schedule'), and explicitly distinguishes this tool from create_schedule_time_range by noting it creates the initial time range. This clearly differentiates it from the sibling tool that adds further ranges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool (creating a schedule with an initial time range) and names the alternative for adding more ranges (create_schedule_time_range). It also discloses the API requirement that at least one time range must exist at creation, giving clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It adds the warning that deletion is irreversible and immediately drops the associated connection, going beyond the annotations' destructiveHint. This provides actionable impact awareness for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loading the action and outcome with no redundant content. The warning is prominently placed and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations, schema, and output schema present, the description covers the key semantic aspects: what is deleted, the immediate connection drop, and irreversibility. It doesn't need to explain return values or the confirm/dry_run mechanics, which the schema already handles.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides complete descriptions for all three parameters (id, confirm, dry_run), including the confirm safety gate. The description adds no parameter-level detail, but the 100% schema coverage supports the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with the resource ('firewall state') and clarifies that a state is an active connection. This precisely distinguishes it from other delete tools operating on different firewall components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for removing a specific firewall state by ID, which is the only tool for this purpose. However, it doesn't explicitly name alternatives or exclusions, so it misses the full mark.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds 'WARNING: This is irreversible' which reinforces and adds context about the permanence of the deletion. It does not mention the safety gates (confirm, dry_run) or the need to apply changes, but those are covered by the schema. The added context earns a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a warning. It is extremely concise, front-loaded with the action, and every word is essential. No filler or repetition. The warning is placed appropriately after the main function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations provide the destructive flag, the description is largely sufficient. It correctly identifies the operation and irreversibility. However, it does not mention that the mapping ID comes from a search, nor does it clarify whether deletion requires a subsequent apply. The schema's apply_immediately parameter defaults to true, which mitigates this, but a brief note about the ID source or workflow would improve completeness. Overall, complex enough that a 4 is reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all parameters, including mapping_id, confirm, dry_run, and apply_immediately. The description only adds 'by ID' which is redundant with the schema. Since the schema already provides full semantics, the description adds minimal value, so a baseline score of 3 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' with the resource '1:1 NAT mapping' and identifies the key 'by ID'. It clearly distinguishes this from sibling tools like search, create, and update, and the warning about irreversibility adds to clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage: when you want to delete a specific mapping identified by its ID. It doesn't explicitly mention alternatives or when not to use it, but the 'by ID' hints at needing the ID from search_nat_onetoone_mappings. No exclusions or prerequisites are stated, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds 'WARNING: This is irreversible', providing critical behavioral context beyond the annotation. This clarifies the severity and lasting consequences of the operation, which is valuable for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core action, followed by a necessary warning. No filler or redundant repetition of schema info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the full schema coverage, annotations, and output schema, the description is mostly sufficient. However, it does not summarize safety mechanisms like the confirm gate or dry_run option, though these are documented in the schema. The irreversible warning and clear purpose make it adequately complete for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameter descriptions present, so the schema handles parameter semantics. The description adds no parameter-specific information beyond referencing 'by ID', which maps to tunable_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Delete'), a clear resource ('system tunable'), and the identification method ('by ID'). This clearly distinguishes it from sibling tools like create_system_tunable, update_system_tunable, and search_system_tunables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing a specific system tunable, but provides no explicit when-to-use guidance, prerequisites, or mention of alternatives. It does not state that the ID should come from search_system_tunables or that confirm must be true, though these are in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds 'irreversible' and an explicit warning, reinforcing the safety-critical nature. It does not mention confirm/dry_run, but those are schema-documented and the destructive hint is already present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One efficient sentence plus a warning. Every word earns its place, and the warning is placed prominently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description conveys the essential action and risk. With a rich schema and output schema present, additional detail is unnecessary. It could mention the required confirm flag, but that is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all four parameters. The description adds no extra parameter guidance beyond 'by ID', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Delete a WireGuard peer by ID.' It clearly states the action and the target, distinguishing it from sibling delete tools like delete_wireguard_tunnel or delete_certificate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a peer ID and intend to delete it. It lacks explicit exclusions or alternative references, but the tool name and 'by ID' make the context reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations readOnlyHint=true and destructiveHint=false already establish the safety profile. The description adds sequential behavioral detail (log search, rule lookup, alias check, suggestion generation) without contradicting the read-only nature. It stops short of stating potential limitations (e.g., log availability or performance).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences: the first clearly states the high-level purpose, the second lists concrete actions. No filler or redundant wording; every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and safety annotations, the description adequately covers purpose and method. It mentions the reliance on firewall logs and the suggestion feature, though it could be more explicit about prerequisites or how it differs from the closely named sibling analyze_blocked_traffic.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description reinforces that source_ip is the primary parameter and others are optional filters, but it adds no new semantic detail beyond what the schema already provides for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'diagnose' and resource 'blocked traffic,' and elaborates the diagnostic process (searching logs, finding matching block/reject rules, checking alias memberships, suggesting fixes). This clearly distinguishes it from simpler sibling tools like get_firewall_log or search_logs_by_ip.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states this is a 'comprehensive analysis' of why traffic is blocked, conveying appropriate use for thorough investigation. It does not explicitly list when-not-to-use or name alternatives, but the context is clear enough to imply when this aggregated diagnostic is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by specifying the exact API endpoint (PATCH /system/restapi/settings) and emphasizing the global impact on all consumers. This adds meaningful context about the scope and method of the modification. Annotations already mark it as destructive and non-readonly, so the extra detail about server-wide impact is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with a clear front-loaded purpose and a necessary warning. Every sentence adds value and there is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema and clear annotations, the description is sufficiently complete. It explains the global scope, the method of change, and adds a warning. Minor missing details like reversibility or immediate effect are not critical given the output schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the 'confirm' parameter with the note 'Must be True to proceed', and schema coverage is 100%. The description does not add extra parameter details, but its warning reinforces why the parameter is necessary. Baseline 3 is appropriate since the schema handles the parameter semantics clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Disable HATEOAS links in API responses on the pfSense server' which clearly identifies the exact action, resource, and scope. It is specific and distinguishable from the sibling tool 'enable_hateoas', so the 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The warning clearly indicates this is a server-wide setting affecting ALL API consumers, which provides important context for when to use it. However, it does not explicitly state 'when not to use' or describe alternatives beyond the implicit sibling 'enable_hateoas'. It gives clear context but no explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond that by disclosing the return content (connection status, established time, local/remote identities, child SA counts) and signaling that all IKE SAs are returned. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the verb+resource and is efficient at roughly 50 words across two sentences. However, the second sentence partially restates the first ('showing active tunnels and their state' vs. 'current state of all IPsec IKE SAs'), so not every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status getter with annotations and an output schema already present, the description is complete: it identifies the resource (IPsec SAs), scopes to IKE SAs, and lists the key data returned. Nothing critical is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4 per the rubric. There is nothing for the description to add about parameter usage; the empty schema is trivially complete at 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence uses a specific verb+resource ('Get IPsec Security Associations (SAs) status') and scopes the tool to IKE SAs, which distinguishes it from the sibling get_ipsec_child_sa_status. The second sentence reinforces the scope with 'current state of all IPsec IKE SAs' and enumerates specific data returned, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for checking overall IPsec tunnel state (connection status, established time, identities) as opposed to child-SA-level detail or configuration tools like search_ipsec_phase1s. However, it never explicitly states when to use this over alternatives or when not to use it, leaving the differentiation to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint, but the description adds a strong WARNING that the operation replaces the running config. It also discloses that every destructive operation automatically captures a pre-change config revision ID, which is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the essential WARNING about replacing the running config. Every sentence earns its place and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, annotations, and full parameter coverage, the description sufficiently explains the tool's purpose, destructive behavior, and how to locate the revision ID. It could explicitly mention the confirm/dry_run workflow, but the schema handles those details, so the description is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers all three parameters with clear descriptions (100% coverage), so the baseline is 3. The description adds only a pointer to get_config_history for finding revision_id, which is already mentioned in the schema's param description. No additional meaning is provided for confirm or dry_run.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Restore pfSense configuration to a previous revision' with a specific verb and resource, and the warning clarifies it replaces the running config. This distinguishes it from related config history tools like get_config_history or delete_config_revision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly tells the agent to use get_config_history to find the revision to restore, providing a concrete companion tool and context for rollback. It does not explicitly state when not to use the tool or mention alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds context beyond that by explaining the data sources (in-memory rollback history and optionally the audit log file) and the conditional behavior based on MCP_AUDIT_LOG. This provides meaningful behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and every sentence adds value. There is no redundant or filler wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With annotations covering safety, schema covering parameters, and an output schema present, the description completes the picture by explaining the underlying data sources and configuration dependency. The only minor omission is explicit mention that this is specific to the guardrail system, but the tool name and content make that obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—all three parameters (limit, risk_filter, tool_filter) have clear descriptions. The tool description does not add any parameter-specific semantics beyond the schema, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Search the guardrail audit log for recent destructive actions taken.' It distinguishes this tool from sibling search tools (e.g., search_firewall_log, search_logs_by_ip) by focusing specifically on the guardrail audit log and destructive actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to audit recent destructive actions. It also mentions the dependency on MCP_AUDIT_LOG configuration. However, it does not explicitly name alternatives or state when not to use it, though the intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive, but the description goes further by disclosing a known server-side bug that may cause failures on large log files, along with a suggested fallback. This is a valuable behavioral detail beyond the structured annotations, informing the agent of potential real-world limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose in the first sentence. The warning in the second sentence is concise, actionable, and adds significant value without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the strong annotations, full schema coverage, and the presence of an output schema, the description provides sufficient context for typical use. The warning about failure modes is an important addition. It could have briefly mentioned when to choose this tool over other log-related tools, but overall it is complete enough for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents all three parameters (ip_address, lines, log_type) with descriptions, achieving 100% coverage. The description itself adds no parameter-specific guidance beyond what the schema 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Search logs for activity related to a specific IP address', which clearly identifies the action (search), the resource (logs), and the specific scope (IP address). This makes the tool's purpose unambiguous and distinguishes it from broader log tools like get_firewall_log or analyze_blocked_traffic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly compare this tool to sibling alternatives or state when to prefer it over other log-search tools. The only usage-related guidance is a failure fallback ('If it fails, suggest reviewing logs via SSH or the pfSense web UI instead'), which is helpful but not comprehensive. The usage context is implied by the purpose statement rather than explicitly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds that this batches pending changes, but annotations already declare idempotentHint=true and destructiveHint=false. It does not disclose potential side effects like service reload or failure conditions if no changes are pending, which would be useful but is offset by the existing 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and contains no redundant or extraneous information. Every word contributes to understanding the tool's purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and an output schema, this description provides enough context: it clearly defines the action and the exact condition for invoking it. An agent can confidently select and call this tool without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to elaborate. The baseline for 0 params is 4, and the description appropriately omits parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Apply pending HAProxy configuration changes' with a specific verb (apply) and resource (HAProxy configuration). It also contextualizes the action by referencing apply_immediately=False, distinguishing it from immediate-apply tools in the sibling list like apply_firewall_changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this after making changes with apply_immediately=False to batch-apply them,' providing clear when-to-use guidance. It does not mention alternatives or exclusions, but the trigger condition is actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds that it sends a POST to the apply endpoint and activates pending changes, which is modest behavioral context. However, it does not disclose potential side effects like service disruption or whether it affects existing tunnels beyond the pending changes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that immediately state the purpose and the mechanism (POST to apply endpoint). No wasted words, and the structure is front-loaded with the action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple apply-changes tool with no parameters and an output schema provided, the description fully conveys what triggers and what it affects. It is complete within the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100% by default. Since there is nothing to document, the baseline of 4 for parameter-less tools applies. The description adds no parameter-specific details because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies pending WireGuard configuration changes, referencing tunnel, peer, and settings changes. This specific verb-resource pairing distinguishes it from sibling apply tools (e.g., apply_firewall_changes, apply_ipsec_changes) by naming WireGuard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: after making WireGuard configuration changes to activate them. It doesn't explicitly list alternatives or exclusions (e.g., when not to use), but the context is clear enough for an agent to select this tool among its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the tool defaults to comparing against the current running config when revision_id_after is not provided. This goes beyond the annotations by explaining a key default behavior, enhancing transparency for an otherwise simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, immediately front-loaded with the primary purpose. The second sentence clarifies the optional parameter behavior without redundancy. Every word earns its place; there is no padding or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only comparison tool with full schema coverage, an output schema, and annotations, this description is complete. It explains the core function and the key optional behavior. Return format details are handled by the output schema, so no further explanation is needed. The tool is fully specified for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented: revision_id_before is 'Earlier revision ID (from get_config_history)' and revision_id_after is 'Later revision ID (optional — defaults to current config)'. The description adds no new parameter semantics beyond paraphrasing the default behavior, which the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Compare two configuration revisions to see what changed.' This is a specific verb ('compare') plus resource ('configuration revisions') that distinguishes it from sibling tools like get_config_revision (which retrieves a single revision) and get_config_history (which lists revisions). The added note about comparing against the current running config further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: when comparing two revisions, and it explains the behavior when revision_id_after is omitted. However, it does not explicitly state alternatives or exclusions, such as 'use get_config_revision to view a single revision instead.' This is clear context without explicit when-not-to-use guidance, matching a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the destructiveHint annotation by explicitly stating the operation is irreversible and cascades to remove all records within the zone. This provides critical behavioral context that annotations alone do not convey, such as the full extent of the destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, a clear WARNING, and a sentence about cascading deletion. Every line adds valuable information without redundancy, making it appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides all essential context for a delete operation: the resource, the irreversible nature, and the cascading effect on records. It does not need to explain return values since an output schema exists. This is complete for an agent to decide whether to invoke the tool and understand its impact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers 100% of parameters, including the confirm safety gate and dry_run behavior. The description adds no additional parameter-specific information beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Delete a BIND DNS zone by ID.' It uses a specific verb and resource, clearly distinguishing it from sibling tools like create_bind_zone or update_bind_zone. The warning about irreversibility and removal of records further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the delete verb and destructive annotation, but there is no explicit when-to-use guidance or discussion of alternatives. It does not mention that this should be used only when a zone is no longer needed, nor does it contrast with update_bind_zone for modifications. However, the clarity of the purpose makes the intended usage fairly obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already define destructiveHint=true and readOnlyHint=false, but the description adds irreversibility and automatic removal of associated Phase 2 entries. This provides critical side-effect disclosure beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences: first states the core action, second delivers the essential warning. No filler or redundancy, and front-loaded with the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a destructive tool, the description covers the crucial operational context (irreversibility and cascade deletion) while schema annotations and descriptions handle parameters and output. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters (100%) with detailed descriptions including confirm, dry_run, apply_immediately, and phase1_id source. The description adds no additional parameter semantics beyond 'by ID', so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States specific action ('Delete') and resource ('IPsec Phase 1 (IKE) entry by ID'), and is clearly distinguishable from sibling tools like delete_ipsec_phase2. The verb+resource pairing is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are mentioned. The cascade warning implies not to use it when retaining Phase 2 entries is desired, but this is indirect rather than a direct usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool runs a connectivity check to verify upstream reachability, which is a behavioral trait beyond static reads and provides useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences convey the purpose and scope directly, front-loading the key phrase 'Check DNS resolver health' and listing components without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all the tool's action space: settings, override counts, system DNS servers, and connectivity check. Given the zero-parameter input and the existence of an output schema, it is complete for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty schema, so the description carries no parameter documentation burden. The baseline for 0-parameter tools applies, and the description appropriately refrains from adding irrelevant parameter detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'checks DNS resolver health' and enumerates specific data retrieved (settings, override counts, system DNS servers, connectivity check). This distinguishes it from related siblings like get_dns_resolver_settings, which only retrieves settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for overall DNS resolver health assessment, but it does not explicitly contrast with sibling tools such as get_dns_resolver_settings or run_ping_diagnostic. There is no when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the scope of IPv4 and IPv6, but does not detail return formats or error behavior. This is acceptable given the annotation coverage, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, resource, and scope with no unnecessary words. It earns its place and is easily parsed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters) and the presence of an output schema, the description is complete. It fully captures the purpose and scope without needing to explain return values or additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so per the baseline rule this scores 4. The description correctly notes the IPv4/IPv6 scope, which is the only relevant parameter-related information, though no explicit parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and the resource 'default gateway settings', further scoping to 'IPv4 and IPv6'. This clearly differentiates it from sibling tools like get_gateway_status and update_default_gateway.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when you need the current default gateway settings. It does not explicitly mention alternatives or exclusions, but the resource is specific enough that the usage context is unambiguous for a zero-parameter getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about the specific settings returned, but does not disclose additional behavioral traits like auth requirements or rate limits. This aligns with the baseline for annotation-covered read operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with a clear title-like phrase followed by a brief explanation. Every sentence adds value, with no unnecessary wording or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema is present, so the description does not need to explain return values. The tool is simple (no parameters), and the description adequately states what the settings contain, which is sufficient given the schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to add parameter semantics, and the schema trivially covers everything (100% coverage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets firewall advanced settings and specifies the content (optimization mode, state timeout values, tuning parameters). This distinguishes it from sibling tools like update_firewall_advanced_settings and other getters, with a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when you need advanced firewall configuration such as optimization mode or state timeout values. It does not explicitly mention alternatives or exclusions, but the context is clear enough for a simple read-only getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description consistently reflects a read operation. It adds context about the contents of the response (risk classifications, rate limits, rollback entries), which is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly written sentences: first states the primary purpose, second lists key data included. No wasted words and appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, strong read-only annotations, and an output schema present, the description covers what the tool returns without needing to explain return values. It is complete for a simple status getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. No parameter explanation is needed, and the description correctly avoids mentioning any.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the current guardrail configuration and recent action history, with specific details about risk classification, rate limits, allowlist status, and rollback entries. This distinguishes it from sibling status tools like get_gateway_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (whenever guardrail status/history is needed) but provides no explicit guidance on alternatives or exclusions. No 'use instead' or 'when not to use' guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds useful behavioral context by enumerating the kind of data returned (traffic selectors, bytes, algorithms, uptime), which goes beyond the annotations and helps set expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds value. The second sentence provides concrete return details without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, strong annotations, and an output schema present, the description covers the essential context. It clearly identifies what the tool returns and is complete for a simple read-only status operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter semantics. The baseline of 4 is appropriate because there is nothing missing; schema coverage is trivially complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('IPsec Child Security Associations status'), and elaborates on what is returned (traffic selectors, bytes transferred, encryption/integrity algorithms, uptime). This clearly distinguishes it from broader status tools like get_ipsec_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use case by focusing on IPsec Child SA status, but it does not explicitly mention when to use this over sibling tools such as get_ipsec_status or diagnose_vpn_status. No alternatives or exclusions are provided, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the resource name, which mirrors the tool name. No additional behavioral context is provided, but with annotations present, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is extremely simple: no parameters, has an output schema, and annotations cover safety. The description is complete for an agent to understand the tool's function without further details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description cannot add parameter meaning. With no parameters, the baseline is 4, and there is nothing else needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the specific resource 'SSH service settings', distinguishing it from sibling get_* tools like get_webgui_settings or get_gateway_status. It's a specific verb+resource pattern.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose of retrieving SSH settings is immediately clear from the description, and the sibling update_ssh_settings provides a clear contrast for read vs. write. However, there is no explicit when-to-use or exclusion guidance, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds the behavioral detail that filtering and pagination are supported, which is relevant for agents expecting potentially large result sets. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous content. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the complete parameter schema and read-only annotations, provides sufficient context for an agent to invoke the tool correctly. The existence of an output schema further reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all 6 parameters with 100% coverage, so the description doesn't need to add much. The phrase 'filtering and pagination' broadly maps to the parameters but doesn't add detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Search' and clearly identifies the resource 'IPsec Phase 1 (IKE) entries', with qualifiers 'filtering and pagination'. This distinguishes it from sibling tools like search_ipsec_phase2s.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to find IPsec Phase1 entries, which is clear context given the tool name. However, it does not explicitly state when to prefer this over alternatives or mention any exclusions, so it doesn't reach a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive behavior. The description adds the batch-apply context and the dependency on previous changes, but does not disclose potential side effects (e.g., service reload or temporary downtime). This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The primary action is front-loaded, followed immediately by usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter apply tool with an output schema present, the description adequately covers purpose and usage. It could mention what happens if no changes are pending, but this is a minor omission. Overall, it is complete enough for the simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter documentation requirement. The description's mention of 'pending changes' is contextual rather than parameter-specific. A baseline of 4 is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Apply pending DNS Forwarder changes') with a specific verb and resource. It is unambiguous and distinguishes itself from sibling apply_* tools by naming the DNS Forwarder subsystem.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use the tool: 'Use this after making changes with apply_immediately=False to batch-apply them.' This provides a clear precondition and usage context, effectively differentiating it from direct update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency and non-destructiveness. The description adds value by revealing that the tool batch-applies changes and shares the firewall apply endpoint, which suggests a potential side effect on firewall rules. This goes beyond structured data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the core purpose. Each sentence adds distinct information: what it does, when to use it, and a note about the endpoint. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with output schema and annotations present, the description covers the essential aspects: action, trigger condition, and endpoint sharing. It doesn't explain how it differs from the closely named apply_nat_changes, but the tool is simple enough that this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so description coverage is trivially 100%. The description meaningfully references apply_immediately=False as a prerequisite from other tools, which clarifies the context without needing to describe any params here. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Apply pending 1:1 NAT changes' with a specific verb and resource, clearly distinguishing this from general NAT or firewall apply tools. It unambiguously identifies the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool: 'after making changes with apply_immediately=False to batch-apply them.' This provides clear context, though it does not explicitly mention alternatives or when not to use it (e.g., vs apply_nat_changes). The reference to sharing the firewall apply endpoint implies a related workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, making the safety profile clear. The description adds meaningful context about the multi-VPN scope and the summary output with error counts, which is useful for setting expectations beyond the annotations. No side effects are disclosed, but none are needed for a read-only diagnostic.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences totaling fewer than 30 words, front-loaded with the main purpose ('Comprehensive VPN health check'). Every sentence adds distinct value—scope and output—without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the full scope of the diagnostic (which VPN types are covered) and the nature of the output (summary counts). Since an output schema exists to detail the return structure, the description need not elaborate further. It lacks only explicit guidance on when to prefer this over more specific status tools, but the scope is adequately clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool accepts zero parameters, so there are no parameter semantics to clarify. The baseline for zero parameters is 4, and the description correctly avoids inventing imaginary parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as a comprehensive VPN health check, specifically naming the covered VPN types (OpenVPN servers/clients, IPsec SAs, WireGuard peers) and the output (per-VPN summary with counts). It distinguishes itself from sibling diagnostic tools by aggregating multiple VPN types into a single check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the tool's scope as a comprehensive check across all VPN types, giving an agent context for when to use it (when a full VPN health overview is needed). However, it does not explicitly mention when not to use it or contrast with alternative tools like get_openvpn_status or other diagnose_* tools, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context about ID instability and why field-based lookup is preferable, which is beyond the annotations. It doesn't disclose edge cases like multiple matches, but given the output schema exists, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and every sentence earns its place. It is concise without losing important guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three well-described parameters and an output schema. The description adds the key context about when to use it. It doesn't explain what happens if no match is found or if multiple matches exist, but the output schema likely conveys return shape. The description is complete enough for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (field, value, endpoint) already described. The description adds only marginal context by saying 'specific field value' and 'stable reference,' but it doesn't introduce new parameter semantics or syntax beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Find an object by a specific field value.' It also differentiates from the many search_* siblings by emphasizing 'safer than using IDs' and its generic applicability across endpoints. This gives a specific verb, resource, and unique positioning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use this instead of IDs when you need a stable reference to an object, since pfSense object IDs change after deletions.' This tells the agent when to choose this tool over alternatives and explains the underlying rationale, which is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, and the description adds meaningful context by listing the diagnostic areas it covers and noting that it returns severity-coded findings. It does not discuss performance implications or authentication, but for a safe read-only report, disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short paragraphs, front-loaded with a clear summary and then a concise bullet-like list of what it checks. Every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only report with an output schema, the description covers purpose, content areas, and output style. It could explicitly mention when to prefer this over individual status tools, but that gap is minor given the schema and annotations handle return structure and safety.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to explain. Baseline score of 4 applies, and the description appropriately avoids extraneous parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a 'Full system health dashboard' that aggregates all diagnostics into one report. It enumerates the specific areas checked (system status, interface health, service status, etc.), distinguishing it from granular tools like get_gateway_status or get_openvpn_server_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a comprehensive health overview via phrases like 'combines all diagnostics' and 'full system health dashboard.' However, it does not explicitly state when not to use it or mention alternative tools for narrower queries, leaving some room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive hints. The description adds meaningful context about SNI-specific behavior and the distinction between additional and default certificates, which is not inferable from the schema alone. It does not disclose actions beyond create/delete, but the schema confirms destructive operations, so this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, and includes a helpful cross-reference. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, an output schema, and annotations. The description covers the tool's purpose and the key alternative path. While it doesn't mention the confirm requirement for delete or return value details, these are already present in the schema and output schema, making the description sufficiently complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for each parameter (e.g., certificate_id required for delete, ssl_certificate required for create). The description does not add parameter-specific semantics beyond what the schema already 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb+resource phrasing: 'Add or remove an additional SNI SSL certificate on an HAProxy frontend.' It clearly distinguishes from sibling tools by scoping to additional SNI certificates and explicitly contrasts with update_haproxy_frontend for default certificates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to update_haproxy_frontend's ssloffloadcert parameter when the intended operation is setting the default certificate, rather than an additional one. This provides clear alternative guidance and contextual usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and non-destructive behavior. The description adds valuable context: firewall logs are raw text and IPs are extracted via pattern matching, alerting the agent to potential data quality issues. Most importantly, it discloses a known upstream bug causing server-side OOM on large log files and suggests a fallback. This goes well beyond the annotations and provides actionable risk mitigation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear front-loaded first sentence. The first paragraph concisely explains the tool's purpose and output fields, and the second paragraph delivers a critical warning in a clearly separated block. Every sentence serves a specific purpose, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description covers the tool's behavior thoroughly: what it does, how it processes data, known limitations, and a fallback. It doesn't explain the full return structure, but that is handled by the output schema. For a read-only analysis tool, this level of completeness is sufficient for an agent to invoke it safely and know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for both parameters: limit has a description with max 50, and group_by_source has a description with threat scoring. The description does not add parameter-specific details beyond what the schema states; it mentions grouping in general but doesn't clarify the boolean behavior or output differences. With high schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Analyze blocked traffic patterns from firewall logs.' It then details the exact behavior—retrieves recent blocked log entries, groups by source IP, shows hit counts, destination IPs, and a threat score. This clearly distinguishes it from siblings like get_firewall_log (raw logs) and diagnose_blocked_traffic (higher-level diagnostic).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when analyzing aggregated blocked traffic patterns rather than viewing raw logs. It provides a fallback in case of failure (SSH/web UI), but it does not explicitly name alternative tools or state when not to use it. Given the presence of sibling tools like get_firewall_log and search_logs_by_ip, being more explicit would earn a 5, but the context is clear enough for an agent to select correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds value by explaining the workflow (after apply_immediately=False changes) and that it batch-applies, going beyond the annotation flags with actionable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, front-loaded with the primary purpose and followed by a single usage guideline. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, output schema present, annotations provided), the description fully covers what the tool does and when to use it. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters; schema coverage is 100% trivially. With no parameters, a baseline of 4 is appropriate since the description need not explain parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Apply pending DHCP server changes'. It also distinguishes from sibling apply_* tools by specifying DHCP, and adds context with the batch-apply usage note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Use this after making changes with apply_immediately=False to batch-apply them.' It tells when to use but does not explicitly state when not to use or name alternatives, though the apply_* siblings are service-specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds that it applies pending (already-created) changes in a batch, clarifying that this is a finalization step rather than a direct mutation. This goes beyond the annotations by describing the workflow position and batch behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences effectively communicate purpose and usage with no redundancy. The first sentence is a clear headline, and the second provides actionable guidance, making efficient use of space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter tool with an output schema and strong annotations, the description is sufficient. It explains what the tool does and when to call it, satisfying all necessary contextual information without over-explaining.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, making the schema coverage trivially complete. The description correctly omits parameter details, and while it does not add parameter-specific information, none is needed. The baseline of 4 for zero-parameter tools is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Apply pending interface changes', identifying the specific resource (interface) and the action (apply). It distinguishes this tool from sibling apply tools such as apply_firewall_changes and apply_nat_changes, and adds the important context of 'pending' changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use this after making changes with apply_immediately=False, giving a clear trigger context for batch application. It does not list alternatives, but the named resource 'interface changes' in the tool name and description naturally separates it from other apply_* utilities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only, idempotent, and non-destructive behavior. The description adds useful context about 'pending' changes and batch application, which aligns with the idempotentHint and does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences. It front-loads the core purpose and immediately follows with the key usage trigger. No unnecessary words or repetitions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, no-parameter apply tool with an output schema. The description covers what is applied (routing changes), when to use it (after deferred changes), and the scope (gateways, static routes, gateway groups). Given the low complexity, the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is nothing to describe. Per the baseline for 0-param tools, a score of 4 is appropriate; the description doesn't need to compensate for schema gaps since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'apply' and the resource 'pending routing changes', explicitly enumerating gateways, static routes, and gateway groups. This clearly distinguishes it from other apply_* sibling tools that target different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: after making changes with apply_immediately=False. It provides clear context for batch application, though it doesn't name exclusion scenarios or alternatives beyond the implied scope of 'routing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by listing the types of checks performed (config, lease pool, conflicts, specific lookup), which helps the agent understand the tool's scope beyond the safety annotations. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loaded with the primary purpose. Every phrase adds value—no filler, repetition, or redundant schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full output schema, complete parameter descriptions, and safety annotations, the description covers the diagnostic scope and optional parameters adequately. For a read-only diagnostic tool, this is sufficient context for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes all three parameters with 100% coverage, so the baseline is 3. The description adds meaning by explicitly tying ip_address and mac_address to the 'looks up a specific MAC or IP address' behavior, reinforcing the optional lookup semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Analyze') and resource ('DHCP service health on an interface'), and enumerates specific checks (server config, lease pool utilization, IP conflicts, optional MAC/IP lookup). This distinguishes it from sibling tools like search_dhcp_leases or get_dhcp_server_config, which are narrower.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when analyzing overall DHCP health and optionally looking up a specific lease. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context by stating it gets CARP status and virtual IPs while checking for unexpected states, which goes beyond the readOnly/destructive annotations. It explains what the diagnostic checks, though it doesn't disclose potential output formats or failure modes. The annotations already cover safety, so this additional behavioral detail is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the primary purpose in the first sentence. It uses two sentences to convey scope and diagnostic behavior without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of parameters and presence of an output schema, the description provides sufficient context for an agent to select and invoke the tool correctly. It explains what the tool checks, its conditionality on CARP configuration, and its relationship to HA status. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema fully covers parameter semantics. The description doesn't need to explain parameters; the baseline for 0-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks CARP/HA status, retrieves virtual IPs, and identifies unexpected CARP VIP states. It uses a specific verb ('check') and resource ('CARP/HA'), distinguishing it from raw status retrieval tools like get_carp_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'if configured' sets a conditional context for when the tool is relevant, implying it is for HA environments. It doesn't explicitly name alternatives or exclusions, but the diagnostic focus (checking unexpected states) makes its use case clear relative to get_carp_status. No explicit when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by listing the content of the returned configuration (enable state, DNSSEC, forwarding mode, DHCP registration, custom options), which helps the agent understand the scope of the response. No behavioral contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action in the first sentence, and the second sentence provides useful elaboration on return contents. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with zero parameters, an output schema, and annotations declaring safety, the description is complete. It tells the agent exactly what it returns and is sufficient for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (vacuously). The baseline for 0 parameters is 4, and the description adds no parameter details (none needed). This is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Get') and specific resource ('current DNS Resolver (Unbound) settings'), and the parenthetical 'Unbound' distinguishes it from the similar sibling tool get_dns_forwarder_settings. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by naming the exact resource (Unbound settings), which implies when to use it, especially compared to the sibling get_dns_forwarder_settings. However, it does not explicitly mention alternatives or exclusions, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, aligning with the 'Get' semantics. The description adds value by listing the specific possible return values (automatic, hybrid, advanced, or disabled), which clarifies what 'mode' means beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that conveys the essential information without any redundancy or filler. It is perfectly sized for the simplicity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only getter with an output schema and safe annotations, this description is fully complete. It clearly states the resource, the possible values, and the read-only nature, covering all necessary context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline for parameter semantics is 4. The description correctly includes no parameter information because none is needed; there is no ambiguity introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a precise resource ('current outbound NAT mode') and enumerates the possible values. This unambiguously distinguishes it from sibling tools like update_nat_outbound_mode and search_nat_outbound_mappings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Get the current...' clearly implies this tool is for reading the current configuration value, providing sufficient context for when to use it. However, it does not explicitly mention alternatives or exclusionary guidance relative to other NAT tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the tool as a safe read operation. The description adds behavioral value by enumerating the exact kinds of data returned (connection status, connected clients, traffic stats, uptime), going beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every phrase adds information. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters, the annotations cover the safety profile, and the output schema exists. The description adequately describes what the tool returns and its scope, making it complete for an agent to decide when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is fully covered by virtue of having no inputs. The description does not need to explain parameters, and the baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets runtime status for all OpenVPN server and client instances, with specific details like connection status, connected clients, traffic statistics, and uptime. This distinguishes it from sibling tools like get_openvpn_server_status and get_openvpn_client_status, which focus on individual components.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to get a comprehensive view of all OpenVPN tunnels, which is clear context. However, it does not explicitly name alternatives or exclude cases where a more specific status tool should be used, so it stops 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive. The description adds the source path (/tmp/rules.debug), the raw nature of the returned rules, and the comparison intent, which is valuable beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. The first sentence identifies the action and source; the second explains the return value. Well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, strong annotations, and an output schema, the description covers purpose, source, return type, and intended use case. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so schema coverage is 100%. Description adds no parameter info but none is needed; baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reads the compiled pf ruleset from /tmp/rules.debug, with a specific purpose: verifying actual enforcement vs config.xml. This distinguishes it from config-reading siblings like search_firewall_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this to verify what pf is actually enforcing vs what's in config.xml. It implies a comparison use case but does not explicitly name alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, which already convey the safe, read-only nature. The description adds no further behavioral details (e.g., authentication requirements or side effects), but none are needed for such a simple getter. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It effectively communicates the tool's purpose in minimal space, earning the highest score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity—zero parameters, a read-only annotation, and an output schema that presumably defines return values—the description is complete. No additional context is required for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is fully covered. As per the rubric, a baseline of 4 is given for 0-parameter tools; the description provides no parameter-specific details because there are none to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the current system hostname and domain' uses a specific verb ('Get') and resource ('hostname and domain'), clearly distinguishing it from sibling tools like get_system_version or get_system_timezone. It precisely states what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool when you need the system's hostname and domain. No exclusions or alternatives are mentioned, but given the trivial nature of a parameterless getter, the intended usage is self-evident. It doesn't explicitly compare to alternatives, but none are directly applicable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context beyond annotations by explaining that the tool fetches the parent certificate rather than querying a standalone list endpoint, which clarifies the underlying mechanism and reinforces the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. The first sentence states the core purpose, and the second provides necessary implementation context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read-only, two parameters, output schema present, annotations cover safety), the description is highly complete. It explains the API quirk and method, while return values are covered by the output schema. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with 100% coverage. The description adds meaning by explaining why parent_id is required ('fetches the parent certificate'), which goes beyond the schema's simple 'ACME certificate ID' description. It does not add detail for search_term, but that is adequately covered by the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List the domain (SAN) validation entries') on a specific resource ('an ACME certificate'). It clearly distinguishes this tool from siblings like search_acme_certificates (which lists certificates) and manage_acme_certificate_domain (which manages domains) by focusing on read-only retrieval of domain entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the API embeds domain lists inline on the certificate object and that this tool fetches the parent certificate, providing clear context for when to use it. It implies the need to first obtain parent_id via search_acme_certificates, though it does not explicitly name an alternative tool or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read behavior is known. The description adds valuable context about the distinction between additional SNI certificates and the default certificate, which is not available from annotations alone. It does not mention pagination or return format, but these are adequately covered by the output schema and parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the tool's purpose, and the note adds a crucial clarification without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple read-only nature, the description adequately explains what it returns, what it excludes, and how it relates to sibling tools. With an existing output schema and full annotation coverage, no further information is needed for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all three parameters, including the source of parent_id. The tool description does not add additional parameter semantics beyond what the schema already states, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('additional SNI SSL certificates bound to an HAProxy frontend'). It distinguishes itself from the default certificate and points to related tools, so there is no ambiguity about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly clarifies that this tool lists only additional SNI certificates, not the default certificate, and directs users to 'update_haproxy_frontend' and 'search_haproxy_frontends' for the default certificate. This provides clear context on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds context by mentioning the specific file (/tmp/rules.debug) and the recompilation behavior. It clarifies that this tool forces a full recompile, going beyond the basic schema. It does not describe potential side effects (e.g., network interruption), but the added context is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with a clear front-loaded main statement, followed by usage guidance. Every sentence adds value, and there is no redundancy or padding. It is appropriately concise for a tool with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the zero-parameter schema, the description is fully complete for the agent to decide when and how to use it. It covers purpose, usage timing, and the specific file affected, and there is no missing information about parameters or return values (output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to explain. The schema covers everything (100% coverage). The description does not need to add parameter details, and the mention of 'apply_immediately parameter on other tools' is context, not this tool's parameters. Baseline 4 is appropriate for empty parameter lists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Force apply pending firewall changes and recompile the pf ruleset.' It specifies the exact resource (firewall changes/pf ruleset) and action (apply and recompile), distinguishing it from sibling apply_* tools by focusing on the firewall/pf context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use: 'Use this after any firewall config change to ensure the compiled ruleset matches the configuration.' It also contrasts with other tools by noting that 'apply_immediately parameter on other tools doesn't always trigger full recompilation,' guiding the agent to prefer this tool when full recompilation is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context about pfSense object IDs being non-persistent array indices that change after deletions, explaining the underlying behavior that motivates the tool's existence. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief paragraphs with no filler. The first sentence states the core action, and the second paragraph provides necessary context and usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the existing output schema, and clear annotations, the description is complete. It covers what, why, and when, and the output schema handles return values. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the endpoint parameter (coverage 100%), and the description reinforces its purpose by noting the tool 're-queries an endpoint'. The phrase adds a slight semantic layer beyond the schema, clarifying that the endpoint is the data source to be refreshed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Refresh object IDs') with the method ('re-querying an endpoint') and the reason ('handles ID changes after deletions'). It is distinct from sibling tools like find_object_by_field or get_* tools, which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use: 'Call this before performing update/delete operations to get fresh IDs.' It also explains why, providing clear context without needing alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![pfsense-mcp-server MCP server](https://glama.ai/mcp/servers/gensecaihq/pfsense-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/gensecaihq/pfsense-mcp-server)

Score Badge

Copy to your README.md:

[![pfsense-mcp-server MCP server](https://glama.ai/mcp/servers/gensecaihq/pfsense-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/gensecaihq/pfsense-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gensecaihq/pfsense-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server