safe-omada-mcp

Server Quality Checklist

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

Latest release: v0.17.0
Disambiguation4/5
Most tools have distinct purposes, but deprecated tools (getClient, getDevice, getRFScanResult) overlap with newer alternatives (listClients, listDevices). The large number of getSitesAps* tools are well-differentiated but could confuse agents due to their similar prefixes.
Naming Consistency4/5
The overwhelming majority of tools follow a clear verb_noun pattern (e.g., getApDetail, listDevices). Minor inconsistencies exist: 'searchDevices' vs. 'getAllDeviceBySite', and 'diagnoseClient' could be more consistent with 'getClientDetail'. However, overall pattern is strong.
Tool Count2/5
With 87 tools, the surface is extremely large and likely overwhelms agents. Many highly granular tools (e.g., separate tools for each AP configuration aspect) could be consolidated. This count far exceeds typical scope for a single server, making selection difficult.
Completeness2/5
The tool set is heavily read-oriented, with extensive get/list operations for devices, clients, and configurations. However, it lacks create, update, or delete operations for most resources (e.g., no add/remove client, no device adoption/removal). This creates dead ends for agents attempting full lifecycle management.
Average 3.5/5 across 87 of 87 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 1 community issues answered or closed in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- 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?
No annotations provided, and description only states it 'gets' status without disclosing side effects, permissions, or rate limits. As a read operation, it likely has minimal behavioral impact, but this is not stated.
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?
Single sentence is concise, but lacks necessary detail. Could be expanded without being 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?
No output schema, no parameter description, and minimal context about return values or scope. Incomplete for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'customHeaders' is not mentioned in the description. With 0% schema coverage, the description should explain the parameter but fails to do so.
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 specifies the action 'Get' and resource 'try-beta firmware switch status' for 'controller', distinguishing it from sibling tools like getUpgradeLogs. However, 'try-beta firmware switch status' 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 versus alternatives like getUpgradeOverviewCritical. Agent must infer usage from 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?
No annotations are provided, and the description lacks behavioral details such as read-only nature, data freshness, or any effects. The tool presumably reads data, but this is not stated.
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 (one sentence) but lacks front-loading of key details and feels incomplete for a tool with 3 parameters.
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 3 parameters, no output schema, and no annotations, the description fails to convey what the returned 'info' entails or how to use the parameters 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 has 100% coverage with descriptions for all parameters, so the description adds no additional meaning. Baseline 3 applies.
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 'Get easy managed switch info' identifies a verb ('Get') and a resource ('easy managed switch info'), but does not specify what information is included or differentiate it from sibling tools like getSwitchDetail or getSitesSwitchesEsGeneralConfig.
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 over alternatives such as getSwitchDetail or getSitesSwitchesEsGeneralConfig.
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?
No annotations are provided, so the description must convey behavioral traits. It merely says 'list,' implying a read-only operation, but does not disclose any side effects, required permissions, or pagination behavior beyond what is 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but it lacks substance. It is not front-loaded with key differentiators.
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 no output schema, 3 parameters (one undocumented), and no behavioral details, the description is incomplete for an agent to fully understand the tool's return value and 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 schema covers 67% of parameters with descriptions for 'page' and 'pageSize'; the description adds no additional meaning. The 'customHeaders' parameter has no description in schema or description. Baseline score 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List firmware pool entries in the upgrade overview,' which indicates a specific verb and resource. However, it does not differentiate from the sibling tool 'listUpgradeFirmwares,' making the purpose somewhat unclear without additional context.
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 'listUpgradeFirmwares' or other firmware-related tools. The description lacks context for selecting the correct tool.
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?
No annotations are provided, and the description fails to disclose any behavioral traits such as side effects, required permissions, rate limits, or error handling. The agent has no information about what happens if the gatewayMac is invalid or if the site is misconfigured.
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, front-loaded phrase. It is concise but lacks structure; every word earns its place but the content is minimal and could be more informative without sacrificing 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 absence of an output schema and the existence of numerous sibling tools (e.g., getGatewayDetail), the description does not explain the return value or how this tool fits into the broader API. It is incomplete for guiding an agent on 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 has 100% coverage with detailed descriptions for all three parameters (siteId, customHeaders, gatewayMac). The tool description adds no additional semantics, so 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 'Get gateway general config' clearly specifies the verb ('Get') and resource ('gateway general config'), distinguishing it from sibling tools like getApGeneralConfig or getSwitchGeneralConfig. However, it does not elaborate on what 'general config' includes, which slightly reduces specificity.
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 getGatewayDetail or listDevices. It lacks any context about prerequisites, selection criteria, or 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?
No annotations are present, so the description must fully disclose behavioral traits. It only states 'Get all port information' without noting if the operation is read-only, has side effects, requires specific permissions, or has rate limits. This is insufficient for safe invocation.
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 well-structured with no wasted words. However, it is too minimal and lacks essential details, sacrificing completeness for brevity. It scores 3 because while concise, it fails to provide sufficient 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?
Given the complexity of switch stacks and the fact that there is no output schema or annotations, the description is incomplete. It does not specify what data is returned, how to handle errors, or prerequisites. With many sibling tools, more context is needed to distinguish this tool's precise function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 67% description coverage (siteId and customHeaders have descriptions, stackId does not). The description 'Get all port information for a switch stack' adds no extra meaning beyond the schema. It does not explain what stackId represents (e.g., how to obtain it) or hint at return values. For a tool with incomplete schema description, this is inadequate.
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 and resource: 'Get all port information for a switch stack.' It is specific and distinct from sibling tools like listSitesCableTestSwitchesPorts which deals with cable test results, so purpose is clear. However, it lacks additional context on what exactly 'port information' includes, 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 guidance is provided on when to use this tool versus alternatives. It does not mention scenarios where a different tool might be more appropriate (e.g., for individual switch ports or cable test results). The description solely 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?
No annotations are provided, so the description carries full burden. It only states 'fetch detailed information' without disclosing behavioral traits such as error handling, rate limits, authentication requirements, or effects of invalid stackId. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is appropriately sized. However, it lacks structure such as bullet points or additional context, and it could be more informative without sacrificing 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 complexity (3 parameters, no output schema, many siblings, no annotations), the description is insufficient. It does not explain the return format, how to obtain a stackId, or how this tool differs from similar tools like getSwitchDetail or listSitesStacks.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (siteId and customHeaders have descriptions, stackId does not). The description adds no additional meaning beyond the schema. It does not explain the format or expected value of stackId, nor does it elaborate on siteId or customHeaders beyond what is in 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 it fetches detailed information for a specific switch stack. This distinguishes it from getSwitchDetail (individual switch) and other stack-related tools, but does not explicitly differentiate from siblings like listSitesStacks or getStackPorts.
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. Siblings include many similar get* tools, but the description provides no context about selection criteria, prerequisites, or when to choose this over others.
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?
With no annotations, the description bears full responsibility for behavioral disclosure. It only repeats the tool name, providing no information about side effects, permissions, rate limits, or read-only nature. This is insufficient for an agent to understand behavioral traits.
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?
While the description is extremely short, it under-specifies the tool's behavior, effectively being a tautology of the name. It fails to include valuable context that would justify its brevity.
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 lack of output schema and nested object parameters, the description should explain what a 'trunk setting' is or outline the response structure. Its single sentence is insufficient for complete 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 coverage is 100%, so the input schema already documents each parameter's meaning. The description adds no new semantic information beyond the schema, but the baseline of 3 is appropriate given 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 it retrieves the trunk setting for an AP, using a specific verb and resource. It distinguishes from sibling tools that target other AP settings (e.g., getSitesApsBridge, getSitesApsChannelLimit) by explicitly naming 'trunk setting'.
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, nor are there exclusions or prerequisites mentioned. While parameter descriptions hint at usage (e.g., siteId defaulting), the description itself offers no context for 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?
No annotations are provided, so the description carries full behavioral disclosure burden. It only states it 'gets' config, implying a read operation, but fails to disclose whether special permissions are needed, error behaviors, or whether it returns partial or full config. The description is too sparse for a mutation-free read tool.
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 (one sentence). While brevity is good, it sacrifices informativeness. The sentence does not earn its place by providing unique insight beyond the tool name itself.
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 no output schema, the description should indicate what the response contains (e.g., power saving settings structure). It does not. With many sibling tools, more context about scope and usage would be beneficial. The description is incomplete for a configuration retrieval 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 baseline is 3. The description adds no extra meaning beyond the schema parameter explanations. The schema already covers siteId, customHeaders, and apMac adequately, so the description offers no additional 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 clearly states the tool retrieves power saving configuration for an AP, using a specific verb and resource. However, it does not differentiate from numerous sibling tools with similar 'getSitesAps*' names, making it harder for an agent to select the correct one.
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, typical use cases, or conditions that might favor other tools. Only parameter descriptions hint at discovering IDs and MACs, but the main text is silent.
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 no annotations provided, the description carries the full burden of disclosing behavioral traits. It only states a read-like operation ('Get'), but does not explicitly confirm it is read-only, idempotent, or non-destructive. No mention of required permissions, rate limits, or side effects. The description is insufficient for an agent to assess safety.
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, which is concise but may be too terse. It lacks structure and front-loading of key information. Every word earns its place, but the brevity leads to ambiguity about the scope of 'general config'.
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 (3 params, no output schema, many sibling tools), the description is incomplete. It does not explain what 'general config' means, what the return value contains, or how this tool differs from similar ones. The schema covers parameters well, but the description fails to provide a complete picture of the tool's 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?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning to the parameters beyond what the schema already provides. The schema descriptions for siteId, customHeaders, and switchMac are clear and adequate. The description does not need to add more, but it also does not enhance understanding.
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 verb 'Get' and the resource 'easy managed switch general config', which is specific enough to indicate the tool's purpose. However, it does not clarify what 'general config' includes, and the term 'easy managed' may be ambiguous without context. It distinguishes from sibling tools like getSwitchGeneralConfig by specifying 'easy managed', but not 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?
No usage guidelines are provided. The description does not help the agent decide when to use this tool over alternatives like getSwitchGeneralConfig or other get*Config tools. No information about prerequisites, when not to use, or alternative tools 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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states the function without revealing that it is a read-only operation, any authentication requirements, or potential rate limits. The description is insufficient for understanding side effects or constraints.
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 front-loads the purpose. It contains no fluff, but could be improved by including parameter details. It is efficient given the tool's simplicity.
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 no output schema and a single complex parameter, the description is too minimal. It does not specify the output format (e.g., a number) or explain the customHeaders parameter. The tool would benefit from additional context about what 'critical upgrades' means and how the count is scoped.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage. The single parameter 'customHeaders' is a nested object with no explanation in the description. The tool description fails to add any meaning or usage hints for the parameter, forcing the agent to rely solely on the schema, which lacks 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 explicitly states the verb 'Get' and the resource 'number of critical firmware upgrades available across managed devices', which is specific and helps the agent understand exactly what this tool returns. It clearly distinguishes from sibling tools like getFirmwareInfo or listUpgradeFirmwares by focusing on the count of critical upgrades.
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 getFirmwareInfo, getFirmwareUpgradePlan, or listUpgradeFirmwares. There is no mention of prerequisites or exclusions, leaving the agent to infer usage context 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?
No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as pagination, ordering, authentication requirements, or read-only nature. The description only restates the basic purpose.
Agents need to know what a tool does to the world before 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 front-loaded and efficient, earning a top score for 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 list tool with no output schema and three parameters (one undocumented), the description is too minimal. It does not cover return format, pagination behavior, or the role of customHeaders, making it incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (page and pageSize have descriptions, customHeaders does not). The description adds no additional meaning beyond the schema, failing to explain the customHeaders parameter or provide usage context for any parameter.
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 'List uploaded firmware files available for manual upgrade,' which identifies the verb and resource. However, it does not distinguish this tool from the similar sibling 'listUpgradeOverviewFirmwares', so it loses 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?
The description provides no guidance on when to use this tool versus alternatives like 'getFirmwareInfo' or 'listUpgradeOverviewFirmwares'. It lacks any when-to-use or when-not-to-use 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?
No annotations are provided, and the description omits behavioral traits. It does not confirm the operation is read-only, mention authorization needs, or describe the response format. The description adds no value beyond the basic purpose.
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 parse. It is not verbose, but could be slightly expanded to include key usage context without becoming wordy.
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 (3 parameters, no output schema, no annotations), the description is insufficient. It does not explain what the configuration contains, any prerequisites beyond the required apMac, or the structure of the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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. The tool description does not add additional meaning beyond 'get IPv6 configuration', so it contributes nothing 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 uses a specific verb 'Get' and resource 'IPv6 configuration for a specific access point', clearly indicating the tool's function. However, it does not differentiate from sibling tools like getApGeneralConfig or getApLldpConfig, which have similar naming patterns.
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. Given the many sibling getAp* tools, explicit comparisons or selection criteria would help the agent choose correctly.
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?
No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as required permissions, data freshness, rate limits, or what happens with missing data. Only states the output type (trends), which is insufficient.
Agents need to know what a tool does to the world before 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 purpose 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 no output schema, the description does not elaborate on the returned data format, time intervals, aggregation, or other structural details. For a time-series tool, this minimalism leaves gaps in understanding the tool's full 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 both siteId and customHeaders having clear descriptions. The tool description adds no additional parameter meaning beyond what the schema already provides. 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 retrieves time-series data for traffic activities with upload and download trends. It uses specific verb 'Get' and resource 'traffic activity time-series data'. However, it does not differentiate from sibling tools like getTrafficDistribution, which may also involve traffic 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?
No explicit guidance on when to use this tool versus alternatives. The description only implies it's for time-series trends, but lacks when-not-to-use or context for selecting this tool over siblings like getDashboardOverview or getTrafficDistribution.
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?
No annotations provided. The description does not disclose any behavioral traits like pagination handling, request limits, or side effects. It only states the basic 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?
One concise sentence that conveys the essential purpose with no wasted words. Well-structured for a 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?
Lacks details about what an upgrade plan includes or what the response looks like. With no output schema, more context is needed to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 2 of 3 parameters with descriptions. The description adds no extra meaning beyond the schema, so it meets the baseline for moderate 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 it retrieves a firmware upgrade plan list. The verb 'Get' and resource 'firmware upgrade plan list' are specific. However, it does not differentiate from sibling tools like getFirmwareInfo or listUpgradeFirmwares.
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. There is no mention of when to prefer it over similar list tools or any 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?
With no annotations provided, the description must disclose behavioral traits. It only states the tool retrieves IP settings, but does not indicate whether it is read-only (implied by 'Get'), error handling, permission requirements, or response behavior. This is insufficient for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. It is front-loaded and efficient, though it sacrifices detail for brevity. Could be expanded to include key behavioral or usage context.
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 lack of an output schema, the description should explain what IP settings are returned and any important limitations (e.g., only current settings, not historical). It also does not mention any side effects or prerequisites beyond the parameter hints. Incomplete for a tool with moderate parameter count.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 covers all three parameters with clear descriptions (100% coverage). The description does not add new semantics beyond the schema, but the schema itself is detailed. 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 action ('Get') and the resource ('IP settings for an AP'), which distinguishes it from sibling tools that retrieve other AP configurations (e.g., getApGeneralConfig, getApIpv6Config). However, it could be slightly more specific by mentioning what type of IP settings (e.g., DHCP/static).
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 text does not provide any guidance on when to use this tool versus alternatives. It does not mention prerequisites, fallback tools, or exclusions. Although the parameter schema includes hints (e.g., 'Use listSites to discover available site IDs'), the description itself offers no 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?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description only says 'Get SIM card used by a gateway,' which implicitly indicates a read operation but does not specify whether it is destructive, requires specific permissions, or if it caches results. It lacks any behavioral context beyond the verb 'Get'. A read-only hint would be helpful but is absent.
Agents need to know what a tool does to the world before 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 sentence of 6 words. It is front-loaded with the purpose and contains no unnecessary information. Every word earns 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?
Given the tool has three parameters, no output schema, and no annotations, the description is too brief. It does not explain what a 'SIM card used by a gateway' means in the context of the network, what the output looks like, or any potential side effects or errors. The agent lacks contextual cues to use this tool correctly. For completeness, it should at least mention that it returns SIM card details like IMSI or ICCID.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all three parameters (siteId, customHeaders, gatewayMac). The description adds no extra meaning beyond what the schema already provides. Baseline is 3 because the schema is descriptive enough, and the description does not improve it.
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 purpose: 'Get SIM card used by a gateway.' It specifies the verb ('Get') and resource ('SIM card used by a gateway'). However, it does not distinguish this from sibling tools like getGatewayDetail or getSitesGatewaysGeneralConfig, which might also return SIM card information. The purpose is clear but not differentiated.
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 when not to use it, or any reference to sibling tools that might provide similar information. An agent would have to infer usage context based solely on the tool name and description, which is insufficient for making an informed choice among many similar 'get' 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?
No annotations provided, so description carries the burden. It only states the tool shows history but omits behavioral details like pagination, ordering, or whether it applies to all devices.
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?
Single sentence, no filler. Efficient but could be slightly more 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?
Minimal description for a tool with 3 parameters (including customHeaders) and no output schema. Lacks details on return fields, filtering, or sorting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%, with page and pageSize described, but customHeaders lacks description. The tool description adds no extra meaning 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 retrieves 'firmware upgrade logs' showing history of upgrade operations. This distinguishes it from siblings like getFirmwareInfo (firmware details) and getFirmwareUpgradePlan (future plans).
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 versus other upgrade-related tools. No alternatives or exclusions 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?
No annotations are provided, so the description must carry the full burden. The description does not disclose that this is a read-only operation, any authentication needs, rate limits, or potential side effects. It is insufficient for safety-critical decisions.
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 at three words, which is efficient. It is front-loaded and contains no filler. However, it may be slightly too minimal for a tool with three parameters and many siblings.
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 no annotations, no output schema, and a simple listing purpose, the description is minimally adequate but lacks context about typical use cases, response structure, or behavior beyond the schema. More detail 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%, and the schema already documents all three parameters with descriptions. The tool description adds no additional information 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List ports on an AP' clearly states the verb (list) and resource (ports on an AP). It is specific and unambiguous, but does not differentiate from sibling tools that may also list ports (e.g., getApDetail, getSwitchDetail).
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, context, or exclusions, which is a significant gap given the large 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?
No annotations provided, so the description carries full burden. It does not disclose whether the tool is read-only, destructive, requires permissions, or the nature of 'incremental results'. The name suggests listing, but description says 'get'; this ambiguity is not resolved.
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, which is concise but at the expense of completeness. It efficiently states the core purpose but omits details about returns or context. It is not verbose, but could better use word count to cover key points.
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?
No output schema and no explanation of what 'incremental results' means or the return format. The description is too brief for a tool that likely has complex return data. Sibling tools like getCableTestFullResults may provide contrast, but this tool's description lacks completeness.
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% with each parameter described. The description adds value beyond schema by noting siteId defaults to config, customHeaders rarely needed, and switchMac hints to use listDevices. This is helpful context that aids correct invocation.
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 resource 'cable test incremental results for a switch', clearly indicating the tool's action. However, it does not distinguish from siblings like getCableTestFullResults or getCableTestLogs, so it loses a point for lack of 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. For example, it does not mention that full results are obtained via getCableTestFullResults or that logs are via getCableTestLogs. Also no prerequisites or context like the need for a compatible switch.
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?
No annotations provided, and the minimal description does not disclose behavioral traits like pagination behavior, authentication requirements, or potential side effects. Only states basic listing action.
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?
Single sentence, no filler. Could be considered too brief, but for a simple list tool it is concise. Front-loaded with the action 'List switch stacks in a site.'
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?
Tool has 4 parameters including pagination and no output schema. The description does not mention pagination, return format, or handling of defaults (e.g., siteId from config). Incomplete for a list operation with pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 with descriptions (100% coverage), so the description adds no extra meaning beyond what the schema provides. 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 tool lists switch stacks in a site. It is specific with verb and resource, but does not explicitly differentiate from sibling tools like getSwitchStackDetail or listSwitchNetworks.
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 such as getSwitchStackDetail (for a single stack) or listSwitchNetworks (for networks). Does not mention prerequisites or 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden but only states basic search and return. Missing details on pagination, rate limits, auth needs, or match semantics.
Agents need to know what a tool does to the world before 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-loading purpose with no 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?
Lacks output schema and does not describe return format, pagination, or sorting. The customHeaders parameter is unexplained, leaving gaps for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description adds no meaning beyond 'search key'. The customHeaders parameter is entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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', the resource 'devices', and the global scope across all sites, distinguishing it from site-specific sibling tools like getAllDeviceBySite.
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 listDevices or getDevice. The description does not provide when-not-to-use 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?
No annotations exist, so the description carries full burden. It does not disclose how 'most active' is defined, whether results are paginated, limited to a top N, or the scope of 'site'. The absence of behavioral details (e.g., data freshness, sorting order) undermines agent understanding.
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?
Single sentence, no wasted words. However, it prioritized brevity over completeness; adding a sentence about usage or return structure would improve 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?
No output schema exists, yet the description does not hint at return fields (e.g., switch names, traffic volume values). It lacks details on aggregation or limits. Given the tool's data-returning nature, this is 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?
Schema coverage is 100% with parameter descriptions already informative (e.g., siteId fallback to OMADA_SITE_ID). The tool description adds no new parameter context beyond what's in 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Get', the resource 'most active switches', and the criterion 'sorted by traffic volume'. It clearly distinguishes this tool from siblings like getDashboardMostActiveEaps (for EAPs) by specifying switches.
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. With over 60 sibling tools, especially similar dashboard tools like getDashboardMostActiveEaps, the lack of explicit usage context severely limits agent 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?
With no annotations, the description carries the full burden but only states the action. It does not disclose behavioral traits like read-only nature, side effects, or prerequisites beyond what is implied by parameter names.
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 quickly conveys the tool's purpose. It is front-loaded and earns its place without 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?
Given the tool has 3 parameters and no output schema or annotations, the description is too brief. It omits details like expected output format, error conditions, or prerequisites for using the switchMac.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 does not add extra meaning beyond the schema fields; it simply restates the overall purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 resource 'ports available for cable test on a switch', clearly distinguishing it from siblings like getCableTestFullResults or getCableTestLogs which deal with results rather than port 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, such as when to invoke getCableTestFullResults instead. The description lacks any when/where 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?
No annotations provided, so description must fully disclose behavior. It says 'Filters the site device list in-process' implying a read operation but does not mention side effects, permissions, error handling, or limitations beyond deprecation. Incomplete for a tool that may be unreliable.
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?
Three sentences each serve a purpose: deprecation, reason, and function. However, the mixed messaging (deprecated yet functional) slightly reduces clarity. Still reasonably 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?
The description does not fully guide the agent on how to use alternatives (e.g., listDevices combined with getApDetail/getGatewayDetail). It lacks explanation of when this tool might still be used or its limitations relative to siblings. No output schema mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 67% with descriptions for siteId and customHeaders, but deviceId (required) lacks description. The description does not add meaning for deviceId beyond being required, so it adds minimal value over schema.
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 states deprecation and suggests using listDevices, but also claims to 'Fetch detailed information for a specific Omada device,' creating confusion about its actual function. The purpose is somewhat clear as a deprecated tool but the active capability is vague.
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 the agent to use listDevices instead, and explains why (no dedicated endpoint). This provides clear when-not and 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?
No annotations provided, so description carries full burden. It states a read operation but no disclosure of side effects, authentication needs, rate limits, or behavior when siteId is omitted. Minimal insight beyond action.
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?
Single sentence, no redundancy. Front-loaded with the key action. Could be slightly expanded without losing conciseness, but current form is 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?
No output schema exists, yet description does not hint at return structure (e.g., list of tag names/IDs). With a complex context of many sibling tools, slight elaboration on response format or default behavior 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% with detailed parameter descriptions. The description adds no parameter-specific information beyond what the schema already provides, so 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?
Description clearly states verb 'Get', resource 'device tags', and scope 'defined in a site'. It is specific and distinguishes from sibling tools that retrieve details of individual devices or other diagnostics.
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. The description does not mention prerequisites, context, or exclusions. With many sibling tools for different device info, guidance is lacking.
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?
No annotations are provided, and the description does not mention any behavioral traits such as side effects, permissions, or rate limits. It merely states what the tool does 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 two sentences, front-loaded with the purpose, and contains no unnecessary information. Every word contributes to clarity.
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 (GET with pagination), the description sufficiently explains the output. However, no output schema is provided, so agents must infer return structure from the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with 67% description coverage (page and pageSize are described; customHeaders is not). The description adds no parameter-specific information, so it fails to add 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 states 'Get the auto-check upgrade plan list showing scheduled firmware upgrade checks across devices.' This clearly identifies the specific verb (Get) and resource (auto-check upgrade plan list), distinguishing it from siblings like getFirmwareUpgradePlan, but could be more explicit about the difference.
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 it is 'useful for auditing upgrade schedules and identifying devices due for automatic firmware updates,' which gives context. However, it does not specify when not to use it or mention alternative tools like getFirmwareUpgradePlan.
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 no annotations provided, the description must disclose behavioral traits. It only indicates a read operation ('Get') but omits details like potential errors (e.g., AP not found), rate limits, or authentication requirements. The lack of output schema further reduces 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, clear sentence. It is front-loaded with the tool's purpose and contains no unnecessary words. While it could be slightly expanded to include return value hints, it is 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 tool's simplicity (three parameters, no output schema), the description is minimally complete. However, it lacks information about the return format or any side effects, which is important since there is no output schema. For a getter, some context on what 'channel limit config' includes 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?
The input schema has 100% description coverage, so the schema already explains the parameters adequately. The description adds no extra meaning beyond the schema. Baseline 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 'Get channel limit config for an AP.' clearly specifies the verb (Get) and resource (channel limit config for an AP). It distinguishes itself from sibling tools like getApsAvailableChannel or getApsBridge by focusing specifically on channel limit.
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 other AP configuration getters. It does not mention prerequisites, such as requiring the AP to exist or the need for certain permissions, nor does it explain when the channel limit config is relevant.
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?
No annotations are provided, so the description carries full burden. It only states the basic action without disclosing behavioral traits such as read-only nature, authentication needs, or pagination behavior (though schema includes pagination params).
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 not front-loaded with key details. It omits important information like pagination or response structure, so conciseness comes at the cost of completeness.
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 4 parameters and no output schema, the description is too brief. It fails to explain what the whitelist contains, how pagination works, or how to interpret results, leaving significant gaps 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?
The schema already covers all parameters (100% coverage), so the baseline is 3. The description adds no additional meaning beyond what the schema provides; it does not explain parameters or their usage context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Get the device whitelist for a site,' specifying the verb, resource, and scope. Among many sibling get* tools, this focuses on a distinct resource (device whitelist), making its 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 does not provide explicit guidance on when to use this tool versus alternatives like listDevices or getDevice. Usage is only implied by the resource name, with no exclusion criteria or 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?
No annotations are provided, and the description only states the purpose without disclosing behavioral traits such as read-only nature, permissions, 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?
Single sentence with no wasted words. Efficient and to the point.
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?
No output schema and minimal description. Lacks context about return format, error handling, and prerequisites (e.g., gateway must be LTE model).
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 each parameter. The description adds no extra meaning, 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 action 'Get' and the resource 'PIN setting for a gateway (LTE model)', distinguishing it from sibling tools that target different devices or 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 explicit guidance on when to use this tool versus alternatives like getSitesGatewaysGeneralConfig. The description provides no 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?
No annotations are provided, so the description must disclose behavioral traits. It indicates a read-like operation but does not mention permissions, error handling, or whether it is destructive. It lacks transparency on required authorization or rate limiting.
Agents need to know what a tool does to the world before 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 redundant information. First sentence states the action, second elaborates on return content. 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 tool with no output schema, the description provides a reasonable list of returned fields. However, it does not mention potential error cases or null results if no uplink is connected, which 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?
The input schema covers all 3 parameters with descriptions. The tool description adds value by listing return fields, but does not enhance parameter semantics 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 clearly states the tool retrieves wired uplink detail for an access point, specifying the returned data (connected switch, port number, link speed, PoE status). It is distinct enough from siblings like getApDetail and getApUplinkConfig, though no explicit differentiation is made.
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 such as getApUplinkConfig or getApDetail. The description only mentions it is useful for mapping topology, but does not specify when not to use it or provide exclusion criteria.
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?
No annotations provided, so description carries burden. It implies a read operation but lacks details on error handling, side effects, or what happens if AP is not found. Adequate but minimal.
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?
Single clear sentence, no fluff. Could mention return format briefly but is efficient for a simple getter.
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?
No output schema and description does not explain what the QoS configuration contains, leaving the agent without expectations of the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameter descriptions. Tool description adds no extra meaning beyond the schema, so 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?
Description clearly states 'Get QoS configuration for a specific access point' with a specific verb and resource, distinguishing it from siblings like getApGeneralConfig or getApVlanConfig.
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. With multiple AP config getters, it does not specify contexts 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?
No annotations are provided, so the description must disclose behavioral traits. It describes a read operation but does not mention any potential side effects, authentication requirements, rate limits, or how many devices are returned. The term 'top' is ambiguous.
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, well-structured sentence that conveys the core functionality. It is concise without being overly brief, though it could be slightly improved by front-loading the action.
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?
There is no output schema, and the description does not explain the return format or how data is ordered. For a tool returning 'top' devices, this lack of output context reduces 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 both parameters (siteId and customHeaders). The description does not add extra meaning beyond what the schema 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 uses a specific verb-resource pair ('Get the top devices by CPU usage') and clearly states the tool's function. The name itself reinforces the purpose, and the output is distinct from sibling tools like getDashboardTopMemoryUsage.
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 identifying overloaded devices but provides no explicit guidance on when to use this tool versus alternatives. No when-not-to-use or alternative tools 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?
With no annotations, the description does not disclose behavioral traits beyond being a read operation. It lacks details on return format, potential side effects, or authorization needs.
Agents need to know what a tool does to the world before 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 wasted words. Every part adds value.
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?
Adequate for a simple query tool: purpose and required parameter (apMac) are clear. Lacks output format details, but the tool's simplicity and schema descriptions fill most 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%, so parameter descriptions are complete. The main description adds no extra meaning beyond the schema, 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 clearly states the action ('Get') and the resource ('available channels for an AP'). It distinguishes from sibling tools like getSitesApsChannelLimit which focuses on channel limits.
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, such as other AP channel or radio queries. No exclusions or context 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?
With no annotations, the description carries full burden. It discloses that the tool returns enabled state and advertised TLVs, which implies a read-only operation. However, it does not mention potential error conditions, authorization requirements, or rate limits. The background on LLDP is informative.
Agents need to know what a tool does to the world before 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 wasted words. The first sentence states the purpose and return values; the second provides useful background on LLDP. Excellent front-loading.
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 'get config' tool with a well-covered schema and no output schema, the description is complete enough. It mentions the key return fields and provides context about LLDP. It could add more about error handling or prerequisites, but 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% with all parameters described. The description does not add extra meaning beyond the schema; it does not elaborate on how parameters affect the request or provide examples beyond what is in the schema. 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 'Get LLDP configuration for an access point' and specifies the return values (enabled state and advertised TLVs). It distinguishes from siblings like getApGeneralConfig by naming the specific protocol, but does not explicitly differentiate from other getAp*Config 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. It does not mention prerequisites, when not to use it, or suggest alternative tools (e.g., getApGeneralConfig for general config). The description is purely descriptive.
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?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does not mention whether the operation is read-only, requires specific permissions, or any side effects. Only describes return content, missing important 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?
Two concise sentences: first states purpose, second adds detail and use case. No wasted words. 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 no output schema and no annotations, the description adequately explains what the tool returns (history, per-port results, lengths, fault detection). It lacks details on pagination, limits, or error handling, but is mostly complete for a diagnostic 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?
Input schema has 100% description coverage, so the schema already documents all parameters. The tool description adds no additional semantic value beyond what the schema provides. 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 verb 'Get' and resource 'cable test logs for a switch' and specifies return content (history, per-port results, etc.). However, it does not differentiate from sibling tool getCableTestFullResults, which likely has overlapping functionality.
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 usefulness for diagnosing physical layer issues but provides no explicit guidance on when not to use this tool or alternatives (e.g., getCableTestFullResults). Usage is implied but lacks 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?
With no annotations, the description bears full responsibility for behavioral disclosure. It indicates a read operation (history), but does not mention if it is read-only, destructive, or has permission requirements. It also lacks details on rate limits or side effects. The time-series return is stated, but format and limitations are omitted.
Agents need to know what a tool does to the world before 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 that front-load the main purpose and include key input requirements. Every sentence is informative with no redundancy, making it highly 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 description covers the tool's purpose and key parameters, it lacks details on the return format of the time-series (e.g., array of objects, intervals), error conditions, or pagination. Given no output schema and many sibling tools, more completeness would be beneficial.
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 value beyond the schema by explaining the default behavior for siteId (using OMADA_SITE_ID config) and that listSites can discover IDs, and by clarifying customHeaders as rarely needed. This exceeds the baseline.
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 gets a historical client count trend over a time range as a time-series. It uses a specific verb ('get') and resource ('historical client count'), and the phrase 'time-series' distinguishes it from sibling tools that might return single counts or client details.
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 is provided on when to use this tool versus alternatives like listClients, listClientsActivity, or listClientsPastConnections. The description only states input requirements but does not mention scenarios or exclusions, leaving the agent to infer 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?
No annotations are provided, so the description must fully disclose behavioral traits. The description only states the action without clarifying that it is read-only, whether it requires specific permissions, or what happens if the AP is not found. This is insufficient for a tool with no 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 seven-word sentence, front-loading the core 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.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should explain the return value and any side effects. It does neither, leaving the agent uninformed about what the response contains or how to handle errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 tool description adds no additional meaning beyond the parameter descriptions in the schema, which already detail siteId, customHeaders, and apMac adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 load balance config for an AP.' uses a specific verb ('Get') and resource ('load balance config for an AP'), clearly distinguishing it from sibling tools that retrieve other AP configurations (e.g., getSitesApsBridge, getSitesApsChannelLimit).
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. The usage is implied by the name and description, but there are no when-not conditions or sibling comparisons provided, limiting the agent's ability to select the correct tool in ambiguous cases.
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 no annotations, the description must convey behavioral traits. It implies a read-only operation ('Get'), which is appropriate. However, it does not disclose details such as authorization requirements, potential side effects, or output format, leaving some ambiguity for a tool that interacts with external systems.
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 at six words, front-loading the core purpose. It is not verbose, though it might benefit from including a brief note on what OFDMA configuration entails without becoming bloated.
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 (a single configuration retrieval) and 100% schema coverage, the description is minimally adequate. However, the lack of an output schema and any hints about the response structure or content means the agent may need additional context for effective 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 covers 100% of parameters with descriptions, so the description adds no extra semantic value beyond what is already in the schema. The baseline score of 3 applies, as the description does not enhance the 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 'Get OFDMA configuration for an AP' clearly specifies the action (get), the resource (OFDMA configuration), and the scope (an AP). It effectively distinguishes this tool from sibling tools that retrieve other AP-specific configurations like getApRadios or getApGeneralConfig.
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 alternative tools for retrieving AP configurations. There is no mention of prerequisites, when not to use it, or how it compares to related siblings, leaving the agent to infer usage without explicit 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?
With no annotations, the description carries full burden but only states it 'Get's data. It does not disclose that this is a read-only operation, any permissions required, or potential side effects. The minimal behavioral detail (just retrieval) is insufficient for safe 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?
A single sentence that contains no fluff. It succinctly conveys the primary action (get), the target resource (most active access points), the scope (in a site), and the ordering (sorted by traffic volume).
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 adequate for a simple retrieval tool with two optional parameters. However, given the lack of an output schema, it would be beneficial to describe the return format (e.g., a list of EAPs with traffic metrics). As it stands, the description leaves the agent guessing about the response 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?
Schema coverage is 100%, with parameter descriptions already explaining siteId defaults and customHeaders rarity. The tool description adds value by specifying the output sorting (by traffic volume) and the context of 'most active', which goes beyond the schema's parameter-level 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 states the tool retrieves the most active access points (EAPs) in a site, sorted by traffic volume. The verb 'Get' and resource 'most active access points' are specific, and the sorting detail distinguishes it from sibling tools like getDashboardMostActiveSwitches.
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. Although it implies the need for a site context (via parameter), there is no explicit mention of when-not-to-use or which sibling tools are better suited for other types of active device queries.
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?
No annotations provided and description lacks behavioral traits beyond 'get' (implying read). Omits details like pagination, ordering, number of devices, or whether results are aggregated.
Agents need to know what a tool does to the world before 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, directly to the point, no unnecessary 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?
No output schema, so description should clarify return format (e.g., list with device names, memory percentages). Currently only states 'top devices by memory usage', leaving agent to infer structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%; description adds no extra parameter meaning. 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?
Clearly states it retrieves top devices by memory usage for a site, distinguishing it from siblings like getDashboardTopCpuUsage which focuses on CPU.
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?
Indicates usefulness for identifying memory-constrained devices but does not provide explicit when-to-use or when-not-to-use guidance relative to 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 description discloses that the tool is a read operation returning paginated history with specific fields (timestamps, SSID/network, traffic, auth type). However, it does not provide details on potential behavioral traits like data retention, rate limits, or authentication requirements beyond what is implied by 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 very concise: two sentences front-loading the key purpose and return content. No unnecessary words or redundancy.
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 complexity of 6 parameters and no output schema, the description is minimally adequate. It explains the purpose and high-level return fields but lacks detail on response structure, time range or how pagination works beyond parameter defaults. Could be more helpful with response format or common usage notes.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 have schema descriptions (100% coverage), so the baseline is 3. The description adds context about the returned fields (timestamps, traffic, etc.) but does not elaborate on individual parameter semantics beyond the schema. Thus, it meets the baseline but does not significantly enhance 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 'Get per-client connection history (paginated)', specifying the verb, resource, and pagination. It distinguishes from siblings like getClient (current status) and listClients (list all clients) by focusing on historical sessions per 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 given on when to use this tool versus siblings such as listClientsPastConnections or getClient. There is no mention of prerequisites, typical use cases, or when alternatives might be preferred.
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 no annotations provided, the description carries the full burden of behavioral disclosure. The word 'Get' implies a read-only operation, which is appropriate. However, the description does not disclose any potential side effects, rate limits, authentication requirements, or data freshness characteristics. It is minimally adequate but lacks depth.
Agents need to know what a tool does to the world before 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 extraneous information. It is front-loaded with the action and resource, making it efficient for an AI agent 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 no output schema and involves nested objects (implied by context). The description does not explain what 'health details' includes or the structure of the response. While the tool's name hints at details, an agent might benefit from knowing key fields returned. It is adequate for simple use but not 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 schema already documents all parameters including siteId, customHeaders, and gatewayMac. The description adds no additional meaning or usage nuances beyond what is in the schema. According to guidelines, baseline is 3 when 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 uses specific verb 'Get' and clearly identifies the resource as 'WAN port health details for a gateway.' This distinguishes it from sibling tools like getGatewayHealth (general health), getGatewayWanStatus (WAN status), and getGatewayPorts (ports listing), making 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 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 specify prerequisites, integration with other tools, or mention when to prefer getGatewayHealth, getGatewayWanStatus, or similar tools. An agent must infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is a read operation ('Get') and specifies the returned data (management VLAN, per-SSID VLAN tagging). With no annotations provided, the description carries the burden of behavioral disclosure; it does not mention authentication needs, rate limits, or error handling, but the core behavior is reasonably clear.
Agents need to know what a tool does to the world before 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 very concise—two sentences with no extraneous information. It front-loads the purpose and immediately follows with useful context on return values and use case.
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 covers the main purpose, what is returned, and a practical use case. Although no output schema exists, the description adequately describes the return. It could be improved by noting potential error conditions or prerequisites, but overall it is sufficient for a simple getter 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 further meaning beyond the schema for the parameters; it mentions the tool's output but not parameter-specific 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 specifies the tool's action ('Get VLAN configuration') and resource (access point). It differentiates from sibling tools by focusing on VLAN-specific settings, but does not explicitly contrast with other AP getters like getApGeneralConfig or getApUplinkConfig.
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 use case ('useful for verifying network segmentation on wireless infrastructure'), implying when to use it. However, it lacks explicit guidance on when not to use or how it compares to alternatives among the many 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?
No annotations are provided, and the description does not disclose any behavioral aspects such as read-only nature, side effects, permissions, or limitations. It only describes the output briefly.
Agents need to know what a tool does to the world before 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 (two sentences) and front-loaded with the action and result. Every sentence 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?
For a simple read operation with no output schema, the description adequately explains what the tool returns. It could mention the format or aggregation details, but it's largely complete enough for 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 coverage is 100% with descriptions for both parameters. The tool description adds no additional parameter information 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 tool retrieves client count distribution by connection type and band, and provides a use case. It distinguishes from sibling tools that focus on individual clients or 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 mentions it's useful for understanding network composition at a glance, implying usage for summary analysis, but does not explicitly state when to use or avoid this tool compared to 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?
No annotations are provided, so the description must disclose behavioral traits. It lacks details on what exactly is returned (e.g., format, aggregation), authentication needs, 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, front-loaded sentence with no 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?
The tool returns statistics but no output schema is provided, and the description fails to describe the return format or time range, leaving a significant information 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?
Despite 100% schema coverage, the description adds value by explaining default site behavior and referencing listSites for discovery, and noting customHeaders is rarely 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 retrieves PoE usage statistics per switch for a site, distinguishing it from other dashboard tools like getDashboardOverview or getDashboardSwitchSummary.
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 clear purpose but offers no guidance on when to use this tool versus alternatives, such as getDashboardSwitchSummary, 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only lists output fields without disclosing behavioral traits: no mention of read-only nature, required permissions, rate limits, error handling, or default behavior when siteId omitted. The description is insufficient for a tool with no 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 sentence that front-loads the purpose and efficiently lists the output components. No extraneous words or repetition. Every part 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 no output schema, the description adequately covers the return values by listing key components. However, it lacks details on error cases, pagination, or how channel utilization is reported. For a simple tool with two optional params, this is mostly 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 input schema already documents both parameters. The tool description does not add any additional meaning beyond what the schema provides, meeting 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 clearly states the tool retrieves a WiFi summary for a site dashboard, listing specific output components (total APs, connected AP count, wireless client count, channel utilization per band, SSID count). This distinguishes it from sibling dashboard tools like getDashboardOverview or getDashboardSwitchSummary.
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 like getDashboardOverview or getClientDetail. The purpose is implied but lacks context such as 'use for a quick WiFi health overview' or exclusions for detailed client data.
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?
No annotations exist, so description bears full burden. It indicates a read operation, but does not disclose potential side effects, rate limits, or authorization requirements beyond what is obvious. The skimpy description suffices for a simple getter, but lacks 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?
Single, well-structured sentence. Front-loaded with action and subject. No extraneous words. Efficient for quick comprehension.
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?
No output schema exists, and the description does not hint at the returned data structure (e.g., fields of the P2P bridge config). For a tool with three parameters and no return specification, the description is incomplete for an agent to fully anticipate the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%; all parameters have descriptions. The tool description adds no additional parameter meaning beyond what the schema already provides (e.g., siteId default, apMac pattern). Baseline is 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?
Description explicitly states the verb 'Get', the resource 'P2P bridge config', and the target 'an AP', clearly distinguishing it from sibling tools like getSitesApsAvailableChannel or getApGeneralConfig.
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 P2P bridge config is needed, but provides no explicit when-not-to-use or alternatives. Parameter descriptions offer some context (default site, discovery methods), but overall guidance is minimal.
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?
No annotations exist, so the description must carry the full burden. It does not explicitly state whether the tool is read-only, whether it requires specific permissions, or what happens if the switch is not found. While it lists the data returned, it lacks transparency on side effects and error handling.
Agents need to know what a tool does to the world before 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 wasted words: the first states the tool's purpose and data returned, the second provides a usage hint. 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?
Given no output schema, the description reasonably covers the return values (model, firmware, CPU, etc.). It lacks mentions of error scenarios or response structure, but is sufficiently complete for a single-item detail 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 description adds marginal value. It reinforces the use of listDevices for the switchMac, but does not provide additional 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?
The description explicitly states the tool fetches full configuration and status for a specific switch, listing multiple specific data fields (model, firmware, CPU/memory, etc.), clearly distinguishing it from sibling tools like getSwitchGeneralConfig or getDevice.
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 advises to use listDevices to get the switchMac, providing a clear prerequisite. However, it does not specify when to prefer this tool over similar ones like getSwitchGeneralConfig or getSwitchStackDetail, leaving usage context 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?
No annotations provided. Description mentions 'quick overview' implying lightweight read, but does not detail pagination, limits, or destructive behavior. Adequate but 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?
Two sentences, clear and front-loaded with no redundancy. Efficiently conveys purpose and returns.
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?
No output schema, but description lists return fields and sorting. Context as dashboard endpoint is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 has full descriptions for both parameters (siteId, customHeaders). Description adds no extra meaning beyond 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 tool retrieves the most active clients sorted by total traffic, listing specific fields. It is distinct from siblings like listClients or getClient.
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 calls it a 'dashboard endpoint for quick overview' but does not specify when to use it over alternatives like listClients or getClientDetail.
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?
No annotations are provided, so the description carries the burden. It mentions the data returned (connection info, IP, etc.) but does not disclose behavioral traits such as read-only nature, error handling (e.g., if MAC not found), authentication needs, or rate limits. The description lacks transparency for a 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 a single, front-loaded sentence that efficiently conveys the tool's action (get detail), target (specific client by MAC), and content (connection info, IP, VLAN, etc.). Every part earns its place with no wasted 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?
The description covers the essential purpose and lists the return data, which is helpful given no output schema. However, it lacks context on error cases, prerequisites (e.g., client must exist), or how to interpret the details. Adequate for a simple get tool but not fully 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 coverage is 100% with descriptions for all three parameters. The description adds minimal extra meaning beyond the schema, such as noting that siteId defaults and customHeaders is rarely needed. This meets baseline expectations but does not significantly enhance 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 purpose: retrieving full detail for a specific client by MAC address, listing connection info, IP, VLAN, signal strength, and traffic stats. It distinguishes from siblings like getClient (presumably basic) and other detail tools (getApDetail, getGatewayDetail).
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 hints at usage by mentioning that siteId can be omitted to use a default, and directs to listSites for discovering site IDs. However, it does not explicitly compare to siblings like getClient or diagnoseClient or state when to use this tool over others.
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?
No annotations are present, so the description must carry the burden. It indicates the operation is read-only (historical list) and paginated, but lacks explicit safety notes, rate limits, or effect on system state. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose and key features (paginated, historical, optional filters). Every word adds value; no filler or redundancy.
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 complexity (9 params, no output schema, no annotations), the description covers the main intent but could expand on pagination details, return structure, or behavior when no filters are applied. It is 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?
Schema coverage is 100%, with detailed descriptions for all 9 parameters. The description only adds minimal context ('optional time range and search filtering'), providing little extra value beyond the schema. 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 retrieves a paginated list of historical known clients with optional time range and search filtering. It uses a specific verb ('Get') and resource ('known clients list'), distinguishing it from sibling tools like getClient or listClients.
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 it is for historical known clients but does not explicitly contrast with active client lists or other related tools. No when-to-use or when-not-to-use guidance is provided, leaving the agent to infer.
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?
No annotations are provided, so the description must disclose behavioral traits. It only states 'Get' and 'Controls', but does not explicitly confirm it is read-only, mention permissions, or describe side effects. Insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before 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, directly to the point, no redundant information. The first sentence states the action, the second clarifies the purpose. Ideal 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?
No output schema is provided, so the description should elaborate on the return value (e.g., structure or typical content of the setting). It only says 'setting' without details, leaving the agent unsure what to expect.
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%, but the tool description adds value by explaining the default site behavior and the optional nature of customHeaders. This enhances meaning beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 verb 'Get', resource '802.1X switch port authentication setting', and provides context ('Controls port-based network access control'). Differentiates from sibling get tools by specifying the exact focus.
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 like getSwitchGeneralConfig or getSwitchDetail. Usage is implied (for retrieving authentication settings) but lacks context on prerequisites or scenarios.
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?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. While it states the tool 'queries statistics' (implying a read operation), it does not explicitly confirm safety, idempotency, or side effects. It also does not mention any required permissions, rate limits, or response structure. The description adds transparency about fuzzy search and filtering but is insufficient for a complete behavior 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 extremely concise with two sentences. The first sentence states the main purpose and capabilities (pagination, filtering), and the second elaborates on the fuzzy search and filter options. Every part is essential and no word is wasted.
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 no output schema, the description should provide guidance on return values. It only says 'statistics', which is vague. The tool has 9 optional parameters, and the description covers most but does not mention any output structure, sorting, or how pagination is handled in results. This is a notable gap for a query tool with moderate 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 schema has 9 parameters with only 22% coverage (page and pageSize have descriptions). The description explains the purpose of 6 parameters: searchMacs, searchNames, searchModels, searchSns (fuzzy search) and filterTag, filterDeviceSeriesType (filtering). It compensates well for the low schema coverage by mapping these to user-facing concepts. The customHeaders parameter is not mentioned, but the overall value added is significant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 verb 'Query' and the resource 'statistics for global adopted devices', with explicit mention of pagination and filtering. This distinguishes it from sibling tools like listDevices (which lists devices without stats) and searchDevices (which searches but doesn't mention stats).
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 indicates the tool supports fuzzy search and filtering, implying use for querying device statistics with pagination. However, it does not provide explicit guidance on when to use this tool over alternatives, nor does it mention exclusions or prerequisites. The context is clear but lacks direct comparison to 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?
No annotations are provided, so the description must disclose behavioral traits. It describes the fetched data but does not mention that the tool is read-only, required permissions, or any potential side effects. The description is acceptable but not detailed enough to fully inform an AI agent about behavioral 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 extremely concise, with two sentences that front-load the purpose and a prerequisite. Every word adds value, and there is no unnecessary text. It is optimally sized for quick reading.
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 (3 parameters, no output schema), the description provides a reasonable summary of returned fields (model, firmware, CPU/memory, etc.). However, it could be more complete by explicitly stating that the output is a JSON object and mentioning any pagination or response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 provides parameter details. The description adds no new information beyond repeating the schema's guidance (e.g., 'use listDevices to get the apMac'). It does not enhance understanding beyond what the input 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 clearly states the tool fetches full configuration and status for a specific access point, listing key data fields. This distinguishes it from sibling tools that fetch specific sub-configurations (e.g., getApGeneralConfig, getApRadios). The verb 'Fetch' and the resource 'access point' are explicit.
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 a prerequisite: 'Use listDevices to get the apMac.' However, it does not provide guidance on when to use this tool vs. alternative sibling tools like getApGeneralConfig or getApRadios. This lack of comparison reduces its usefulness for tool 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?
No annotations are provided, so the description carries the full burden. It implies a read-only operation by describing data retrieval, but does not explicitly state non-destructiveness, required permissions, or other behavioral aspects. The description adds moderate transparency by specifying the returned 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 one sentence plus a succinct directive, front-loading the purpose without extra words. Every sentence earns its place, achieving maximum 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?
Despite lacking an output schema, the description enumerates the key data fields returned, giving a clear picture of the tool's output. For a three-parameter tool with moderate complexity, this provides sufficient completeness for an agent to understand the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%; the description does not add significant new meaning beyond the schema definitions. It reinforces the use of listDevices for the apMac parameter, which is already in the schema description. Baseline 3 is appropriate as the schema already documents parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 that the tool retrieves radio status for a specific AP, listing concrete data elements (2.4GHz/5GHz config, channel, TX power, channel utilization, client count). It distinguishes from sibling tools that provide broader device details or configuration by focusing on per-AP radio 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 instructs users to use listDevices to obtain the apMac, which is helpful. However, it lacks guidance on when not to use this tool or how it differs from similar tools like getRadiosConfig. Usage context is partially provided but without 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?
No annotations are provided, so the description carries full burden. It states that it returns specific SNMP fields, which is adequate. However, it does not disclose any potential side effects, authentication requirements, or rate limiting. The behavior described is consistent with a 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: one stating the action and returned fields, and one providing a use case. No extraneous information. 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 the tool has 3 parameters, no output schema, and no annotations, the description covers the purpose, returned fields, and use case adequately. It does not describe output format or prerequisites, but for a read operation with clear parameter instructions, it 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?
Schema coverage is 100%, and each parameter already has a detailed description in the schema. The tool description does not add any additional meaning or context for the parameters beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 SNMP configuration for an access point, lists returned fields (SNMP version, community strings, trap settings, enabled state), and provides a use case (auditing). This distinguishes it from sibling tools like getApDetail or getApGeneralConfig.
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 it is useful for auditing SNMP configurations but does not provide explicit guidance on when to use it vs alternatives, nor does it mention when not to use it. With many sibling tools, more explicit usage context would help.
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?
No annotations exist, so the description carries full burden. It discloses that the tool returns specific data (uplink mode, settings, failover) and implies it is a read operation. It does not mention side effects, authentication needs, or rate limits, but the stated purpose is transparent enough.
Agents need to know what a tool does to the world before 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: first states purpose and returns, second adds usage context. No redundancy, front-loaded, 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?
Without an output schema, the description explains return values at a high level (mode, settings, failover). This is adequate for most use cases, though details on data types or structure are missing. Given the tool's simplicity, it is mostly 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%, with each parameter described in the schema (siteId includes default behavior, apMac includes pattern and reference to listDevices, customHeaders is explained). The description adds no further 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 clearly states the tool retrieves uplink configuration for an access point, listing specific return fields (mode, settings, failover). It distinguishes effectively from sibling tools like getApDetail or getUplinkWiredDetail by focusing on uplink config.
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 it is useful for understanding mesh topology and wired uplink assignments, providing implicit usage context. However, it does not explicitly state when to avoid this tool or compare with alternatives like getUplinkWiredDetail or getMeshStatistics.
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 no annotations, the description carries the full burden. It explains the return data (cable status, length, fault location) but omits behavioral aspects like idempotency, required authentication, side effects, or error conditions. It is adequate but could be more thorough.
Agents need to know what a tool does to the world before 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. The first sentence states the primary action clearly, and the second adds a comparison. 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 no output schema, the description provides a good overview of the output content. The parameter schema is fully described. The sibling context shows a related tool. It lacks mention of whether results are paginated or the exact format, but overall it is complete enough 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?
All three parameters have schema descriptions with 100% coverage, so the description adds no extra meaning beyond what the schema provides. The baseline is 3, and no additional context is given 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 the verb ('Get'), the specific resource ('full cable test results for all ports on a switch'), and the scope ('all ports'). It also differentiates from the sibling tool 'getCableTestLogs' by noting it provides more detailed data.
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 only implies when to use this tool by stating it's 'more detailed than getCableTestLogs', but it does not provide explicit usage guidelines, such as scenarios where one should choose this over the simpler log tool, or any prerequisites like switch access permissions.
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?
No annotations exist, so the description must carry full behavioral transparency. It describes the tool as fetching data and lists the returned fields, but does not explicitly state it is read-only, mention potential side effects, or any required permissions. The description 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 two sentences: the first clearly explains what the tool does, and the second provides a helpful prerequisite hint. No extraneous information; each 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 three parameters and no output schema, the description lists key return items (model, firmware, etc.), which is sufficient for an agent to understand the tool's output. It does not discuss error conditions or response size, but for a simple fetch tool this 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?
Schema coverage is 100% with clear descriptions for each parameter. The description adds minimal semantic value beyond the schema—only the guidance to use listDevices for the gatewayMac. This meets the baseline for a tool with 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 fetches 'full configuration and status for a specific gateway' and lists specific items like model, firmware, CPU/memory, etc. It distinguishes from sibling tools like getGatewayHealth or getGatewayPorts which focus on subsets.
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 advises to 'Use listDevices to get the gatewayMac,' which is a prerequisite. However, it does not explicitly state when to use this tool versus alternatives like getGatewayHealth or getGatewayLanStatus, nor does it provide 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?
No annotations provided. Description explains it retrieves traffic volume and utilization, but doesn't disclose potential rate limits, data availability, or that it targets a specific site's ISP links. Reasonable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with core function, no redundancy. Every sentence adds value: operation, detail, use cases.
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 4 params (2 required), no output schema, description covers what the tool does and parameter roles. Lacks indication of output structure (e.g., list of links with metrics), which would help agents parse results. Still, fairly complete for a read 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 coverage is 100% with descriptions for all parameters. Description reiterates that start/end are Unix timestamps but adds no new semantic info beyond schema. Baseline 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?
Description clearly states 'Get per-WAN ISP link load over a time range' with specific verb and resource. Lists use cases (load balancing, saturated links, failover) that distinguish it from sibling tools like getGatewayHealth or getTrafficDistribution.
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?
Description mentions useful scenarios but lacks explicit guidance on when not to use or alternatives. Does not state prerequisites like having a gateway with WAN links.
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?
No annotations are provided, so the description must fully disclose behavioral traits. It describes the return type (configuration) but does not explicitly state that the operation is read-only, idempotent, or free of side effects. It also does not mention authentication requirements or rate limits.
Agents need to know what a tool does to the world before 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 with no redundant words. The first sentence states the core functionality, and the second provides differentiation from a sibling tool. Every word serves a 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 the tool's moderate complexity (nested objects, no output schema), the description lists the return fields (band, channel, etc.) and mentions the radio bands (2.4GHz, 5GHz, 6GHz). It does not describe the structure of the output or note whether all radios are always present, but it provides sufficient context for typical 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 schema already provides 100% coverage with descriptions for each parameter, so the description adds limited semantic value beyond listing the returned fields. The description mentions 'band, channel, transmit power, channel width, and enabled SSIDs' which aligns with the parameters but does not elaborate on how parameters affect behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 ('per-radio configuration for an access point'), listing detailed settings (band, channel, etc.), and explicitly distinguishes from the sibling tool 'getApRadios' by noting it returns configuration vs runtime 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 explicitly states when to use this tool ('Returns configuration') and when to use an alternative ('Use getApRadios for runtime radio status'), providing clear context. However, it does not mention scenarios to avoid using this tool or prerequisites beyond the parameters.
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?
No annotations are provided, so the description carries full burden. It implies read-only list operation without side effects, but does not disclose pagination, permission requirements, error behavior, or any constraints. For a simple list, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is extremely concise: one sentence stating the action, one sentence listing returns. No fluff, front-loaded with the key purpose. 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?
Given no output schema and simple parameters, the description covers the essential context: what the tool does, what it returns, and the distinction from adopted devices. Could mention pagination or default site behavior more explicitly, but 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%, and schema descriptions for siteId (default site config, discover via listSites) and customHeaders (rarely needed) are already detailed. The tool description adds no additional parameter information 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?
Description clearly states the tool lists devices discovered but not yet adopted, and specifies returned fields (type, MAC, IP, model). This distinguishes it from sibling tools like listDevices which likely list adopted devices.
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?
Description does not provide explicit guidance on when to use this tool versus alternatives like listDevices. There is no mention of prerequisites or context for adoption workflow, leaving usage decision 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?
With no annotations, the description carries full burden. It states the tool returns a list of devices with MAC addresses and connection details, implying a read-only operation. However, it lacks details on permissions, rate limits, error conditions (e.g., if an AP doesn't have switch ports), or whether data is live or cached.
Agents need to know what a tool does to the world before 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, highly concise, and front-loaded with the main action. Every sentence adds value, with no redundant or wasted 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?
The description is adequate for a simple tool with well-documented parameters, but lacks completeness due to no output schema. It mentions return content but not structure, and does not cover potential errors, limitations, or prerequisites beyond 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 baseline is 3. The description does not add extra meaning beyond the schema; it mentions return values (device MACs) but not parameter details. The schema already thoroughly describes the three 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 'Get' and specific resource 'wired downlink devices connected to an access point's LAN port'. It distinguishes from sibling tools by focusing on wired downlink devices, which is unique among the many get commands for APs.
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 a clear context by specifying it is useful for APs with built-in switch ports (e.g., EAP615-Wall). However, it does not explicitly state when not to use it or suggest alternatives, though it is implied that it is for wired downlink devices only.
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?
No annotations provided, so the description carries full burden. It implies a read operation ('Get') and lists output fields, but lacks details on authentication, rate limits, response structure, or error behavior. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a clear purpose: what the tool does, its advantage over siblings, and a prerequisite. 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?
Without an output schema, the description lists output fields but not the structure (e.g., array per port). Given 3 params and nested objects, it is somewhat complete but could specify return format more clearly.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 well-described in schema. The description adds a hint for gatewayMac ('Use listDevices'), but otherwise adds no new semantic meaning 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 'Get all WAN and LAN port details' and resource 'gateway', listing output fields. It distinguishes from sibling tools getGatewayWanStatus and getGatewayLanStatus by noting it is more detailed.
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 (when detailed port info is needed) and mentions alternatives (less detailed siblings) and a prerequisite (use listDevices to get gatewayMac). No explicit when-not or exclusion, but sufficient 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?
No annotations are provided, so the description carries the full burden. It states the return value is 'VLAN interface assignments across all stack members', but does not disclose side effects, permissions, or confirm read-only behavior. For a simple GET, this is minimally 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?
Two sentences with no extraneous information. The first sentence states the purpose, the second provides a key prerequisite reference. Efficient 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?
The description is very brief. It does not explain pagination behavior, error conditions, or contrast with sibling tools like listSwitchNetworks. Given the tool's simplicity and rich schema, it is adequate but leaves gaps for a less-informed 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% coverage, with all 5 parameters fully described in the schema. The description adds no additional parameter semantics beyond referencing getSwitchStackDetail for stackId, 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 clearly states the verb 'get' and the resource 'VLAN network list for a switch stack', and distinguishes itself from sibling tools by noting which tool to use to obtain the required stackId.
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 tool is for retrieving VLAN network lists for a switch stack and provides a prerequisite hint to use getSwitchStackDetail for the stackId. It does not explicitly contrast with similar list tools like listSwitchNetworks, but the context is adequate.
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?
No annotations are provided, so the description carries full burden. It does not state whether the tool is read-only, destructive, or has any side effects. The pagination parameters (page, pageSize) imply paginated results but the description omits this behavior. Basic behavioral disclosure 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?
Two sentences plus a brief note. No redundant information, front-loaded with main purpose. 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 no output schema, so the description must cover return format and pagination. It briefly describes output (which VLANs assigned to ports) but does not mention pagination behavior or result structure. Given 5 parameters and common list tool patterns, the description is adequate but misses key 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?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the context for switchMac (use listDevices) and siteId default behavior. It also clarifies the output briefly. However, some parameter descriptions (page, pageSize) add 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 the tool lists VLAN network assignments for a switch, specifying output includes VLAN ports with tagged/untagged configuration. It mentions a prerequisite step (use listDevices to get switchMac). No sibling tool explicitly covers switch VLAN assignments, so it is well-distinguished.
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 a clear usage context: to retrieve VLAN assignments for a switch. It explicitly tells the user to use listDevices to obtain the switchMac parameter. However, it does not mention when not to use this tool or contrast with similar tools like getSwitchDetail or getSwitchGeneralConfig, leaving some ambiguity.
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?
No annotations are provided, so the description carries the full burden. It discloses that it includes offline and disconnected devices, which is the key behavioral trait. However, it does not mention any other behaviors like pagination, rate limits, or whether the operation is read-only (implied but not explicit).
Agents need to know what a tool does to the world before 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 with three short sentences. It front-loads the core action ('Get all devices in a site') and immediately adds the key differentiator. Every sentence adds value 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 no output schema, the description reasonably sets expectations: it returns the full device inventory including offline/disconnected devices, useful for auditing. It does not explain return structure or potential delays, but for a simple list tool with optional parameters, 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?
The input schema has 100% coverage with descriptions for both parameters. The tool description does not add additional meaning beyond what the schema already provides (e.g., siteId defaults to config, customHeaders rarely needed). 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 gets all devices in a site, including offline and disconnected devices. It distinguishes itself from the sibling tool listDevices by specifying that listDevices may filter to active-only, making the purpose and differentiation explicit.
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 when to use this tool (for full inventory, auditing) and contrasts with listDevices (which may filter to active-only). It does not explicitly state when not to use it, but the comparison provides sufficient guidance 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?
No annotations provided, so description carries full burden. It describes what the tool returns but does not disclose any behavioral traits such as side effects, rate limits, or authorization requirements. The read-only nature is implied by 'Get' and the description of returning configuration, which is acceptable but 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?
Two sentences, zero waste. The first sentence clearly states purpose and returned data, the second directs to an alternative tool. 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?
The description lists several specific configuration fields (device name, LED settings, etc.), which gives a good sense of the output despite lacking an output schema. However, it ends with 'and other global AP parameters', which is vague. Overall, it is fairly complete for a read tool with good 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 coverage is 100% with detailed parameter descriptions for all three parameters. The description does not add any additional meaning beyond what the schema already provides, so it meets 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?
Description uses a specific verb ('Get') and resource ('general configuration for an access point'), lists specific returned fields, and explicitly distinguishes from sibling tool getApDetail which returns runtime status instead.
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?
Description provides clear guidance: use this for stored configuration, use getApDetail for runtime status. It gives an explicit alternative but does not provide further 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?
No annotations, so description must disclose behavior. It lists outputs but lacks details on side effects, performance, or error states. Adequate for a read-only overview.
Agents need to know what a tool does to the world before 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, concise and front-loaded with essential information. No redundant 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?
No output schema, but description covers key return data. For a high-level overview tool, this suffices, though more detail on data structure could help.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameter descriptions. The description does not add extra meaning beyond what schema already provides, 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 it retrieves site overview topology including device counts, client counts, connectivity graph, and health status. It positions itself as a first call, distinguishing from more specific sibling tools like getDashboardPoEUsage.
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 says 'Good first call to understand what's in the network', implying initial exploration. Does not list when not to use or alternatives, but context implies it's high-level.
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?
No annotations are provided, so the description carries full burden. It indicates a read operation (Get) and lists returned data, but does not explicitly state read-only nature, side effects, error conditions, or auth requirements. Adequate but could be more explicit.
Agents need to know what a tool does to the world before 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 with clear front-loaded purpose and enumerated data fields. No redundant information. Efficient and 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?
No output schema but description lists specific return fields, sufficient for a summary tool. Parameters are fully covered. Missing details on error handling or format, but overall complete for expected 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 descriptions for both parameters (siteId and customHeaders) are present and add context beyond name/type. siteId description explains default behavior and how to get IDs; customHeaders notes it's rarely needed. This adds 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 clearly states the action 'Get' and the resource 'switch summary for a site dashboard', listing specific data fields (switch count, ports, PoE, bandwidth). This differentiates it from sibling tools like getDashboardPoEUsage or getDashboardWifiSummary.
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 'for a site dashboard' but lacks explicit when-to-use or when-not-to-use guidance versus sibling tools. The siteId parameter description provides some guidance on default site and discovery via listSites, but no alternative comparisons.
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?
No annotations provided, so description carries burden. It discloses return values and implies read-only behavior, but doesn't mention permissions, error handling, or side effects. Adequate but not extra.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-load purpose and output, with a helpful prerequisite. 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?
No output schema exists, but description explains return fields sufficiently. Parameter documentation is in schema. For a simple info tool, it 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 descriptions cover 100% of parameters. Tool description repeats the 'use listDevices' hint already in the schema, adding no new semantics beyond what's already 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?
Description clearly states it gets firmware information for a device, listing specific return fields. It distinguishes from siblings like getFirmwareUpgradePlan by focusing on a single device's latest available firmware.
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 prerequisite (use listDevices for deviceMac) but lacks explicit guidance on when to use this vs alternatives, 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?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states the output fields but does not mention any side effects, authorization requirements, or error behaviors (e.g., what happens if the gateway is offline). The description is adequate for a simple read operation but leaves some ambiguity.
Agents need to know what a tool does to the world before 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 consists of two sentences: the first defines the purpose and returned data, the second provides a prerequisite hint. There is no extraneous information, and the key action is front-loaded. Every word serves a clear 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 simplicity of the tool (3 parameters, no output schema, no nested objects in input), the description covers the essential aspects: what it does, what it returns, and how to get a required parameter. It could be more explicit about the output structure (e.g., indicating it returns an object per port), but overall it is sufficiently complete for an agent to understand its usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% (all three parameters have descriptions in the schema). The tool description adds the hint to use listDevices for gatewayMac, but this is already present in the parameter's description. The added value beyond the schema is minimal, 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 verb 'Get' and the resource 'LAN port status' for a specific gateway, listing the exact details returned (link state, speed, duplex, connected device, VLAN assignment). This distinguishes it from siblings like getGatewayPorts or getGatewayWanStatus, which target different port types or statuses.
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 includes a prerequisite directive ('Use listDevices to get the gatewayMac.'), which guides the agent on how to obtain a required parameter. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternative tools, such as specifying that this should be used only for LAN port details and not for WAN or general gateway information.
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?
No annotations provided, so description must disclose behavior. It describes return fields (WAN IP, DNS, etc.) but does not mention permissions, rate limits, or whether the operation is read-only. For a status tool, this is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no superfluous content. The first sentence defines the action and return fields; the second adds a prerequisite. 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?
No output schema exists, but the description lists key return fields (WAN IP, DNS, uptime, link speed, TX/RX rates, connection type). It does not mention error cases or pagination, but for a straightforward status tool, coverage is good.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameters. The tool description adds only a repetition of the prerequisite for gatewayMac ('Use listDevices') and mentions return values, which are not parameter semantics. 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 'Get' and the resource 'WAN port status and connectivity information for a specific gateway'. It lists specific return fields and distinguishes from sibling tools like getGatewayLanStatus by focusing on WAN.
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 includes a prerequisite hint: 'Use listDevices to find the gatewayMac.' It implies usage for checking WAN status but does not explicitly contrast with alternatives like getGatewayHealth or getGatewayLanStatus.
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?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states what the tool returns, but does not mention side effects, authorization needs, error conditions, or any destructive potential. As a read operation, it likely has no destructive side effects, but this is not explicitly stated.
Agents need to know what a tool does to the world before 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. The first sentence states the purpose and return value; the second provides a crucial usage hint. Every sentence adds value with 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?
Given the lack of an output schema, the description adequately explains what the tool returns ('configured LAG/trunk groups including member ports, load balancing mode, and status'). It also covers the key parameter requirement (stackId) and how to obtain it. It could mention the response format (e.g., array) or error cases, but overall it is sufficient for a straightforward 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 schema already has 100% coverage with descriptions for all three parameters. The description adds value by advising to use getSwitchStackDetail to find the stackId, which is not in the schema description. This helps the agent understand how to populate the required 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 specifies the tool's purpose: getting the Link Aggregation Group (LAG) list for a switch stack. It names the resource (LAG/trunk groups), the action (get), and the details returned (member ports, load balancing mode, status). It also differentiates from siblings like getStackPorts by focusing on LAG configuration.
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 a key prerequisite: 'Use getSwitchStackDetail to get the stackId,' guiding the agent on how to obtain the required stackId parameter. However, it does not explicitly state when not to use this tool or compare it to siblings like getSwitchStackDetail or getStackPorts.
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?
No annotations are provided, so the description must carry the full burden. It discloses that the result is stored (not real-time) and that a scan is prerequisite, but lacks details on error handling, rate limits, or authorization requirements. The deprecation is a notable 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 two sentences plus a brief note, front-loaded with the deprecation marker. Every sentence adds value: deprecation warning, purpose, data returned, prerequisite. No 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?
Without an output schema, the description lists the key data returned (neighbouring networks, utilization, interference, RSSI). It mentions the prerequisite scan. It does not detail structure or pagination, but for a deprecated tool, the information is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 description adds minimal value beyond the schema—only the workflow tip to use triggerRfScan first. The parameters are well-documented in the schema itself, so the description does not significantly 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 clearly states it retrieves the last RF scan results for an access point, including specific data types (neighbouring networks, utilization, interference, RSSI). The deprecation note is upfront, and the purpose is distinct from 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use triggerRfScan first before calling this tool. The deprecation warning serves as a strong indicator to avoid if possible. However, no explicit alternatives or when-not-to-use scenarios are mentioned beyond deprecation.
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?
With no annotations, the description communicates that this is a read-only retrieval of traffic data over a time range, with no mention of destructive side effects. It adds context on timestamp format but could be more explicit about its non-modifying 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 long, directly stating the purpose and providing context on what the breakdown reveals. No wasted words; 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 no output schema, the description hints at the output shape (breakdown by category) and time range constraints. It is fairly complete for a retrieval tool with well-documented parameters, though output structure could be more explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 (siteId, customHeaders, start, end) with descriptions. The description only reiterates the timestamp format already in the schema, adding no significant new meaning beyond the structured data.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 retrieves traffic distribution by protocol and application type over a time range, with a specific breakdown by categories like video and gaming. This differentiates it from sibling tools such as getDashboardTrafficActivities.
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 identifying bandwidth consumption but does not provide explicit guidance on when to use this tool versus alternatives like getDashboardTrafficActivities or other traffic-related tools. No when-not or exclusion criteria 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?
With no annotations, the description carries full burden. It discloses the output type (time-series data) and content (new, active, disconnected clients), but does not mention potential behavioral traits like data granularity, pagination, or effects of missing parameters. It is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no waste. First sentence states action and source, second specifies output, third suggests use case. 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?
Given the absence of an output schema and the moderate complexity (4 optional parameters), the description covers the purpose and output well but lacks details on default behaviors (e.g., siteId, date range defaults) and output format specifics.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 75% (3 of 4 parameters have descriptions). The description adds context about time-series data but does not improve understanding of individual parameters beyond the schema. Baseline is 3 due to 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 'Get client activity statistics over time from the dashboard' with specific output details (new, active, disconnected clients for wireless and wired). This distinguishes it from sibling tools like listClients (current clients) and listClientsPastConnections (past connections).
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 says 'Useful for monitoring client connection trends and activity patterns,' which implies usage context. However, it does not explicitly state when not to use it or name alternative tools, so it lacks explicit exclusion 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?
No annotations exist, so the description carries full burden. It describes the output fields and that it lists provisioned devices, which is a read operation. However, it does not mention pagination, rate limits, or potential size of results, which could be important.
Agents need to know what a tool does to the world before 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 efficient sentences: first covers purpose and return data, second gives direct guidance to sibling tools. No unnecessary 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?
Given no output schema, the description explicitly lists key return fields (MAC, model, firmware, etc.) which is helpful. It lacks pagination details but overall provides sufficient context for agent to use 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 descriptions for both parameters (siteId with default behavior, customHeaders as rare). The tool description itself does not add extra parameter detail, but the schema already provides adequate meaning; 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 it lists all provisioned network devices (gateways, switches, APs) in a site and lists the returned fields. It explicitly distinguishes from sibling detail tools by mentioning using MAC addresses from this output as input to getGatewayDetail, etc.
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 tells when to use the tool (to list all adopted devices) and how to use the output with detail tools. It does not explicitly state when not to use it or mention alternatives like listPendingDevices, but the context is 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?
With no annotations, the description carries full burden. It discloses the composite nature and accepted identifier formats (MAC, IP, hostname) but does not describe authentication needs, rate limits, error handling, or return behavior beyond implied aggregation.
Agents need to know what a tool does to the world before 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: first defines composite nature, second gives usage guidance. No wasted words. Front-loaded with key benefit and components.
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 no output schema and moderate complexity, description covers purpose, usage, and identifier format. Missing details on default site behavior, error handling, or return structure. Adequate but incomplete for a composite 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?
Schema covers identifier and siteId with descriptions. Description adds valuable detail on identifier formats (MAC with colon/hyphen, IP, hostname) and states siteId is optional. Does not mention customHeaders, leaving some gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 it is a 'composite client diagnostic' that combines connection status, detailed info (VLAN, signal, rate limit, group policy), and recent connection history (last 10 sessions). It clearly distinguishes from sibling tools by being a single call aggregating multiple data points.
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 specific use cases: 'troubleshooting why a device can't connect, has poor performance, or keeps disconnecting.' Implicitly suggests when not to use (if only one piece of data needed, use getClient or getClientDetail), 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?
No annotations are provided, so the description carries full burden. It mentions auto-discovery and optional skip-discovery, which is good. However, it does not state whether the tool is read-only or any side effects, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before 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 main purpose and use cases. No filler words; every sentence 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?
Given no output schema, the description adequately explains return fields (CPU, memory, firmware, ports, WAN/LAN statuses). It covers the composite nature and parameter behavior, making it complete for most use cases.
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 67% (customHeaders not described). The description adds meaning: siteId can be omitted to use default, and gatewayMac can be provided to skip discovery. These clarifications go 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 is a 'Composite gateway health check' that auto-discovers the site gateway and retrieves full detail (CPU, memory, firmware, ports), WAN port statuses, and LAN interface statuses. This distinguishes it from sibling tools like getGatewayDetail, getGatewayWanStatus, getGatewayLanStatus.
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 explicit scenarios: 'Use when diagnosing internet connectivity issues, WAN failover, or gateway performance problems.' However, it does not mention when NOT to use it or explicitly name 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?
No annotations are provided, so the description bears full responsibility. It explicitly states the tool is read-only and describes the output fields (backhaul link quality, signal strength, throughput, hop count). It does not mention any side effects, auth requirements, or rate limits, but for a read operation the provided information 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 consists of two short sentences, no redundant words, and is front-loaded with the key action and resource. Every word serves a 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 the moderate complexity (3 parameters, no output schema, many sibling tools), the description sufficiently explains what the tool returns and its use case. It lacks explicit mention of prerequisites (e.g., mesh-enabled APs must exist) and does not explain the structure of the return value beyond listing fields. However, for a straightforward read tool this 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?
Schema coverage is 100%: all three parameters have descriptive schema entries (siteId, customHeaders, apMac). The tool description does not elaborate on parameters further; it focuses on the return value. The description adds context about the default behavior of siteId and references to listSites and listDevices, but these are already covered in the schema. Baseline 3 is appropriate as the description adds no new 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 clearly states the verb 'Get' and the resource 'mesh link statistics for an access point', and specifies the returned fields (link quality, signal strength, throughput, hop count). This distinguishes it from sibling tools like getCableTestFullResults or getRFScanResult that focus on other diagnostics.
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 notes the tool is 'useful for diagnosing mesh network performance', providing clear context for when to use it. However, it does not explicitly exclude scenarios or mention alternatives among the many sibling tools (e.g., getNetworkHealthSummary). A direct reference to when not to use this tool would improve clarity.
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?
Discloses that individual sections gracefully degrade if an endpoint is unavailable, adding valuable behavioral context beyond a simple listing. With no annotations provided, this is a useful disclosure of error handling 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?
Three concise sentences that front-load the tool's purpose and usage guidance. Every sentence adds value—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 composite nature and lack of output schema, the description adequately covers the main sections (dashboard, WAN, clients, threats) and graceful degradation. Minor omission of response format or pagination, but acceptable for a snapshot 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 already covers both parameters (siteId, customHeaders) with 100% description coverage. The description does not add additional 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 is a 'composite health snapshot' that combines dashboard overview, internet/WAN status, client distribution, and recent active threats. It distinguishes from siblings (e.g., getDashboardOverview, getGatewayHealth) by being a single aggregated call.
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 recommends using this as the first call when checking if everything is working or starting a troubleshooting session. While it doesn't enumerate when not to use it, the guidance is clear and practical, implying deeper dives via other 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?
No annotations are provided, so the description carries the full burden. It describes a read operation ('Get') with no mention of destructive actions, auth needs, rate limits, or side effects. This is minimally sufficient but could be more explicit.
Agents need to know what a tool does to the world before 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 cover purpose, scope, and a critical prerequisite. No wasted words; all content is essential and 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 high schema coverage (100%) and simple parameter structure (3 params, 1 required), the description adequately covers what the tool does and how to use it. Without an output schema, it provides enough context about the returned data.
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% parameter description coverage, so baseline is 3. The description adds value by clarifying how to obtain the 'switchMac' parameter via listDevices, providing practical guidance 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 ('Get'), names the resource ('general configuration for a switch'), and enumerates included items (device name, LED settings, LLDP, flow control, other global parameters). It clearly distinguishes this tool from siblings like getSwitchDetail, which focus on more specific aspects.
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 a direct prerequisite hint ('Use listDevices to get switchMac values'), implying when to use this tool (after listing devices). While it does not explicitly state when not to use it or list alternatives, the context is clear from the sibling list.
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?
No annotations provided, so description carries full burden. It accurately describes the read-only retrieval behavior and output fields. However, it does not mention potential issues like pagination or response size limits, which is acceptable for a simple list tool.
Agents need to know what a tool does to the world before 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 wasted words. Front-loaded with the action and resource, followed by output details. Every sentence serves a clear 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?
Despite no output schema, the description thoroughly enumerates the returned fields (MAC, IP, hostname, device, SSID, signal strength, traffic, online status). This covers the key information an agent would need 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%, so the schema already documents both parameters (siteId, customHeaders) with descriptions. The tool description adds no additional meaning beyond what's in 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 uses a specific verb ('List all network clients') and clearly identifies the resource (clients connected to a site). It provides a comprehensive list of returned details (MAC, IP, hostname, etc.), distinguishing it from tools like 'getClient' (specific client) and 'listClientsActivity'.
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 use cases: 'Use this to audit connected devices or find a specific client by name or MAC.' While it doesn't directly mention when not to use it or alternatives, the guidance is clear and practical for typical scenarios.
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?
No annotations provided, so the description carries full burden. It discloses the read-only nature and return fields (timestamps, traffic, duration, device details), and mentions pagination, filtering, sorting, and fuzzy search, but could add more safety 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 sentences with no fluff: first states purpose, second lists features. 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?
The description covers the main features and return fields, but given 9 parameters and absence of output schema, it could elaborate on how to combine parameters or the exact structure of returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema by explicitly stating 'Supports pagination, filtering by time range and guest status, sorting by last seen time, and fuzzy search by name/MAC/SSID,' which maps directly to multiple parameters and their 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 states 'Get client past connection list with historical connection data' with specific details on returned data and supported features, clearly distinguishing it from sibling tools like getClient (current) and listClients (current 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 description implies usage for historical connections but does not explicitly state when to use this tool over alternatives like listClientsActivity or getGridClientHistory, nor does it provide exclusions or preconditions.
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?
With no annotations, the description carries full burden for behavioral disclosure. It explains the tool 'filters the site client list in-process to emulate a per-client lookup', indicating a non-optimal implementation. However, it could further note read-only nature and lack of 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 concise (three sentences) and front-loaded with the most important deprecation warning. Every sentence adds value 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?
Given the deprecated status and absence of output schema, the description covers key aspects: alternatives, mode of operation, and basic function. It could mention output format or additional limitations, but overall it's sufficiently complete for a simple fetch 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 coverage is 67% (siteId and customHeaders have descriptions, clientId does not). The description adds no extra parameter details beyond the tool's purpose, but the required clientId is implicitly clear. Baseline score of 3 is appropriate for medium coverage without additional explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 (fetch details for a specific Omada client) and explicitly distinguishes from sibling tools by recommending listClients and getClientDetail as alternatives. It also notes the deprecated status, which adds 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?
The description provides explicit when-to-use and when-not-to-use guidance: it declares the tool deprecated and recommends 'Use listClients instead' and 'getClientDetail is also available' for MAC-based lookups, helping agents choose 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?
Describes return data (upload/download throughput) and that it stores previous results, which is helpful. No annotations provided, so description carries full burden; it adequately discloses read-only behavior but could mention handling of missing results.
Agents need to know what a tool does to the world before 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-loaded with purpose and followed by usage guidance. No unnecessary 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?
Covers key aspects: what it does, how to initiate a test, and required param. With no output schema, could detail return format but enough for typical 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 coverage is 100%, so description adds little beyond schema. It notes siteId default and customHeaders rareness but does not deepen understanding of 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?
Clearly states 'Get the last speed test results for an access point', specifying verb and resource. Distinguishes from sibling tools by focusing on speed test results and referencing triggerSpeedTest.
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 to 'Use triggerSpeedTest first to initiate a new test; this returns stored results', providing clear context on when to use this tool vs 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:

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

Score Badge

Copy to your README.md:

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

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/gaspareduard/Omada-mcp'

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