tplink-omada-mcp

Server Quality Checklist

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

Latest release: v0.15.0
Disambiguation3/5
Many tools have similar names (e.g., getApDetail vs getApGeneralConfig, getApRadios vs getRadiosConfig), but descriptions clarify differences. However, the sheer number of specific tools (e.g., 12 getSitesAps* tools) increases chance of misselection.
Naming Consistency4/5
Predominantly uses snake_case with verb_noun pattern (get_, list_). Minor inconsistencies like getClientsDistribution vs getClientDetail, and long names like getSitesHealthGatewaysWansDetails, but overall predictable.
Tool Count2/5
84 tools is excessive for most use cases. While the domain is broad, many tools could be consolidated (e.g., cable test logs vs full results). Presence of deprecated tools further inflates count.
Completeness2/5
Tool set is heavily read-oriented (get/list) with few mutation tools (missing triggerRfScan/triggerSpeedTest from provided list). Lacks create/update/delete for most resources, leaving agents unable to perform basic network management tasks.
Average 3.5/5 across 84 of 84 tools scored. Lowest: 1.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 0 of 3 community issues answered or closed in the last 6 months
- 0 commits in the last 12 weeks
- Last stable release on March 31, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

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 read-only nature, side effects, or required permissions. It simply states what the tool gets without any 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short but overly vague. Conciseness without clarity is ineffective. It fails to earn its place by providing useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/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 many sibling tools, the description is severely incomplete. It does not explain what switches are returned, the format of info, or how it differs from other switch-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. However, the description adds no extra meaning beyond the schema details for the parameters (e.g., switchMac, siteId, customHeaders).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get easy managed switch info.' is vague. It uses a generic verb 'Get' without specifying what information is returned. It does not differentiate 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 guidance is provided on when to use this tool versus alternatives. The description lacks any context about prerequisites, preferred scenarios, or exclusions.
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 adds no behavioral context. It does not state whether the operation is read-only, what side effects exist, or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single underspecified sentence. It is concise but lacks necessary detail; it does not front-load important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and many sibling tools, the description is inadequate. It does not explain return value, pagination, or how it relates to other tools.
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% (siteId and customHeaders described, stackId missing). The description provides no additional parameter semantics beyond the schema, failing to compensate for the gap.
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 resource ('all port information for a switch stack'). It is specific enough to differentiate from siblings like getGatewayPorts or 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 on when to use this tool versus alternatives. The description does not mention any prerequisites or context for usage.
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 does not disclose behavioral traits such as read-only nature, required permissions, or side effects. The agent has no information about what happens when calling this 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 concise but too minimal. It front-loads the purpose but omits important details. Every sentence earns its place, but it could include more context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the number of sibling tools and no output schema, the description is incomplete. It does not explain the return value, how the config differs from other tools, or provide any contextual cues for selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add any extra meaning beyond what the input schema already provides for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves general configuration for easy-managed switches, distinguishing it from 'getSwitchGeneralConfig' for regular switches. However, it does not explicitly differentiate from other sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool over alternatives. The description lacks context about prerequisites or scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It indicates a read operation but lacks details on side effects, authentication requirements, rate limits, or behavior on errors.
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 short and to the point, but it achieves conciseness at the expense of necessary detail, making it merely adequate.
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 annotations, the description should provide more context about return values, result structure, or edge cases. It is insufficiently 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?
Input schema covers 100% of parameters with descriptions. The description adds no additional parameter context, so it meets the baseline without exceeding it.
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 gateway general config.' clearly identifies the action and resource, but does not specify what 'general config' includes, leaving ambiguity compared to sibling tools like getGatewayDetail.
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 (e.g., getGatewayDetail), nor any prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral traits. It only states 'list', implying a read operation, but does not disclose pagination behavior, rate limits, or any side effects. For a tool with no annotations, this 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is overly brief. While front-loaded, it would benefit from additional detail without becoming verbose. As is, it is adequate but minimal.
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, no output schema, and moderate complexity, the description is incomplete. It does not describe the output format or how to interpret results, leaving the agent with insufficient context for correct invocation.
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 schema description coverage is 67% (page and pageSize have descriptions, customHeaders does not). The description adds no information about parameters beyond what is in the schema, failing to clarify the purpose of customHeaders or provide usage context.
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 'List' and the resource 'firmware pool entries in the upgrade overview'. It is specific and distinguishes this tool from siblings like listUpgradeFirmwares, though the distinction is subtle.
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 indicate when to use this tool versus alternatives like listUpgradeFirmwares, nor does it mention any prerequisites 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?
With no annotations, the description carries the full burden for behavioral transparency. It fails to disclose pagination behavior, sorting, or what happens when no plans exist. The description is too brief.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous content. However, it may be too minimal for effective use.
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, and no annotations, the description is insufficient. It does not explain what the response contains, pagination, or error handling.
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% (page and pageSize have descriptions, customHeaders does not). The description adds no additional meaning beyond the schema. The undocumented customHeaders parameter is not explained.
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 list of firmware upgrade plans for devices managed by the controller. However, it does not differentiate itself from sibling tools like getUpgradeLogs or getUpgradeOverviewCritical that also deal with 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. There is no mention of prerequisites or context, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description implies a read operation via 'Get', but does not disclose any behavioral traits such as permissions, rate limits, or whether the status is real-time. Minimal but acceptable.
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 with no unnecessary words. Front-loads the action. However, lacks structure to include parameter details or examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a tool with a non-trivial parameter and sibling tools. Missing output schema, parameter explanation, and differentiation from similar upgrade tools.
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 the description does not mention the 'customHeaders' parameter at all. The description adds no meaning beyond the schema, leaving the parameter unexplained.
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 try-beta firmware switch status for the controller,' clearly identifying the resource and action. However, it does not distinguish itself from sibling tool 'getUpgradeOverviewCritical', leaving ambiguity about when to use each.
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 or getFirmwareInfo. The description provides no context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It only states it's a read operation but omits details like pagination behavior, required permissions, or what the whitelist contains. The schema shows pagination parameters, but the description adds no value.
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 excessively short (one sentence), which is concise but under-specified. It front-loads the purpose but lacks structure and fails to elaborate on key aspects.
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 complexity of paginated lists, the description is incomplete. It does not explain what the whitelist is, the response format, or how pagination works.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed parameter descriptions (e.g., siteId, page, pageSize). The tool description does not add any additional meaning beyond the schema, earning the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'device whitelist for a site', which is specific enough to distinguish from many sibling tools that target other resources (e.g., getApDetail, getClient). However, it does not explicitly differentiate from other 'getSites*' tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like getAllDeviceBySite or getDevice, nor any context about prerequisites or limitations.
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 'Get', implying a read operation, but lacks details on permissions, rate limits, or any side effects. For a configuration retrieval tool, more transparency would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no extraneous information, achieving maximum 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, the tool description fails to explain the return format or content of the IPv6 configuration. With three parameters and no behavioral context, the description is too minimal to be considered 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 descriptions for all three parameters. The tool description adds no additional meaning beyond the schema, meeting the baseline for high-coverage cases.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'IPv6 configuration for a specific access point', which is distinct from sibling tools like getApGeneralConfig or getApVlanConfig. However, it does not elaborate on what the IPv6 configuration contains.
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 usage guidelines are provided. The parameter descriptions for apMac and siteId indirectly suggest prerequisites (listDevices, listSites), but there is no mention of when to use this tool versus alternatives or any context-specific advice.
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 mentions 'showing power consumption per switch' without disclosing behavioral traits like authentication needs, rate limits, or non-destructive nature. For a read operation, basic safety info is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, but it could benefit from additional context on usage or output. It is front-loaded and efficient, earning a high score for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks detail on output format, return values, or pagination. Despite low complexity, the absence of output schema means the description should compensate, but it only vaguely mentions 'showing power consumption per switch'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds no extra meaning beyond what the schema already provides (siteId optional with default, customHeaders rarely needed). 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 gets PoE usage statistics per switch, which is a specific verb and resource. It distinguishes from siblings like getDashboardOverview due to its unique focus on PoE, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, nor any conditions or exclusions. The description only states what it does without context on appropriate usage 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?
With no annotations, the description bears full burden but lacks disclosure of traits like result limit, sorting order, real-time vs cached data, or authorization needs. Only states the basic function.
Agents need to know what a tool does to the world before 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, direct and efficient. No filler, every word contributes to stating the tool's function and utility.
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 presence of many sibling tools, the description is too sparse. It doesn't explain what 'top' means (e.g., top 5, top 10), how results are sorted, or how to use the output. Insufficient for effective tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters. However, the tool description adds no extra meaning beyond the schema; it doesn't mention the parameters or their roles.
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 top devices by CPU usage for a site and identifies overloaded devices. It uses a specific verb and resource, and the purpose is distinguishable from siblings like getDashboardTopMemoryUsage, though 'top' could be more precisely defined.
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 (e.g., getDashboardTopMemoryUsage). The user must infer from the name and description alone; no when-not-to-use or alternative suggestions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only says 'get', implying read-only, but does not explicitly state behavioral traits like idempotency, authentication needs, or rate limits. The description adds minimal value beyond the name.
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?
A single, short sentence that is direct and to the point. While concise, it could include more detail without significant bloat.
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, so the description should provide some hint about return values. It does not. Given the number of sibling tools, the description is too minimal to help an agent choose correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters well. The description does not add any additional meaning or context for the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool gets 'channel limit config for an AP', which is a specific verb and resource. However, it does not differentiate from sibling tools like getSitesApsAvailableChannel, which might be confused for a similar purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites or context, such as requiring apMac or siteId.
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 does not mention that this is a read-only operation, whether it requires authentication, rate limits, or what happens if the AP is not found. The description is silent on behavior beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is perfectly concise and front-loaded. Every word is necessary and no extraneous information is included.
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 annotations, the description lacks crucial context. It does not explain what the IP settings response contains (e.g., DHCP vs static, IPv4 details), nor does it address the complex environment of many sibling tools. The description is too minimal to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, including apMac, siteId, and customHeaders. The description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get IP settings for an AP.' It uses a specific verb and resource, but does not differentiate from sibling tools like getApGeneralConfig or getApIpv6Config, which also retrieve AP settings. The word 'IP settings' is somewhat generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as getApIpv6Config for IPv6 or getApGeneralConfig for general settings. No prerequisites or scenarios 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 available, the description carries the full burden of behavioral disclosure. It only states a read operation ('Get') but omits any details about potential side effects (none expected), required permissions, or output format. 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 extremely concise (one sentence), but it sacrifices content for brevity. It is front-loaded with the key action but does not fully earn its place, lacking any auxiliary information that an agent might find helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with a well-documented input schema and no output schema, the description is minimally adequate. However, it does not explain what the load balance config consists of or any return value format, leaving some 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?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not clarify parameter usage or constraints beyond what is already defined 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 the verb 'Get' and the resource 'load balance config for an AP', making the purpose immediately understandable. However, it does not differentiate from sibling tools like getApGeneralConfig or getApRadios, which also retrieve AP configurations.
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 scenarios where this tool is specifically needed, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only says 'Get', implying a read operation, but does not confirm read-only behavior, auth requirements, rate limits, or any side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single, front-loaded sentence. Every word is necessary and there is no wasted text.
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, so the description should explain what the response contains. It does not. Additionally, no annotations exist to aid completeness. The description is overly minimal given the complexity of retrieving a power saving configuration.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all parameters with descriptions. The tool description adds no extra parameter information. Baseline score of 3 is appropriate as the schema does the heavy lifting.
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'), the resource ('power saving config'), and the entity ('an AP'). It is specific and unambiguous, though it does not distinguish among many sibling tools like getApGeneralConfig or getApRadios.
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 are no exclusions, prerequisites, or context indicating the appropriate scenarios for this call.
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 behavioral traits like read-only nature, required permissions, or side effects. Minimal information is given beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. However, it lacks context that could improve clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief for a tool with no output schema and three parameters. It does not explain what 'health details' includes, the return format, or any prerequisites, making it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are described in the input schema (100% coverage), so the description adds no additional meaning. The baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves WAN port health details for a gateway, with a specific verb and resource. It is distinct from sibling tools like getGatewayWanStatus or getGatewayPorts, but does not explicitly differentiate itself.
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 getGatewayWanStatus or getGatewayPorts. The description lacks any contextual usage advice.
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 behavioral traits such as pagination, ordering, side effects, or authentication requirements. It does not mention that the tool is read-only or any potential rate limits, leaving agents with minimal understanding of behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded and to the point. However, it could be slightly improved by adding details about pagination or result format without adding much length.
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 the presence of many sibling tools, the description is incomplete. It does not specify the return structure, that results are paginated, or how customHeaders might be used. The tool has 3 parameters and a nested object, but the description provides no additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (page and pageSize have descriptions). The tool description does not add any meaning beyond what the schema already provides; for example, it does not explain the purpose of customHeaders. Baseline score of 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves firmware upgrade logs showing history of upgrade operations. It uses a specific verb ('Get') and resource ('firmware upgrade logs'), and distinguishes from sibling tools like getFirmwareInfo and getFirmwareUpgradePlan.
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 getUpgradeOverviewCritical or listUpgradeFirmwares. The description only explains what the tool does, not when to invoke it or when not to.
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 describes input capabilities (pagination, filtering). It does not disclose whether the operation is read-only, idempotent, or any side effects, rate limits, or response structure beyond inferred 'statistics'.
Agents need to know what a tool does to the world before 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 establishes core action and pagination, second lists supported filters. No redundant words, well front-loaded.
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 9 parameters, no output schema, no annotations, and many siblings, the description is too brief. It omits what the returned 'statistics' include, pagination metadata, and any constraints like date ranges or data freshness, leaving important gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (22%), but the description adds context for fuzzy search and filtering by tag or device series type, covering the main search parameters. However, it omits details on parameter formats (e.g., comma-separated vs single value) and does not address customHeaders, leaving gaps for 9 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies tool as querying statistics for global adopted devices with pagination and filtering. It distinguishes from siblings like listDevices and searchDevices by focusing on 'statistics', though the exact nature of statistics (e.g., aggregated counts) is not elaborated.
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, searchDevices, or getDevice. The description only states what it does, not when it is appropriate 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?
With no annotations provided, the description carries the full burden. It does not disclose behavioral traits like pagination support (though the schema includes page and pageSize), read-only nature, or response structure. A minimal list description would benefit from mentioning these aspects.
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 seven words, with no filler. However, it could be slightly more informative without sacrificing brevity, e.g., mentioning pagination or the purpose of the list.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (list with pagination, no output schema, nested objects), the description fails to explain pagination behavior, what the list returns, or how it fits with sibling tools. It is insufficient for an agent to use correctly without additional context.
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 description adds no information about the parameters beyond what the schema already provides. While the schema covers 67% of parameters with descriptions, the description doesn't clarify the purpose of customHeaders or compensate for the uncovered parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List), resource (uploaded firmware files), and context (available for manual upgrade). This distinguishes it from siblings like listUpgradeOverviewFirmwares and getFirmwareInfo, which have different scopes.
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 getFirmwareInfo or listUpgradeOverviewFirmwares. It lacks any context about prerequisites, use cases, 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 provided, and description does not disclose any behavioral traits such as idempotency, side effects, or authorization requirements. This leaves agents uninformed about safe usage.
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?
Description is a single sentence, which is concise, but overly terse. It lacks any elaboration on context or return value, making it minimally adequate.
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 no annotations, the description should provide more context about what the SIM card info includes and how it fits into the broader API. It does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 baseline is 3. Description adds no extra parameter meaning beyond what the schema already provides, but does not detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 SIM card used by a gateway.' Uses specific verb and resource, and distinguishes from sibling tools which are other getters for different device aspects or actions.
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 conditions, prerequisites, or exclusions. Some hints exist in input schema but not in description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a simple read operation (getting a count), but with no annotations, it does not disclose any potential side effects, required permissions, or constraints. It is minimally adequate for a straightforward query.
Agents need to know what a tool does to the world before calling it. Descriptions 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 of 12 words. Every word is necessary and there is no redundancy, achieving optimal 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?
Despite having no output schema, the description only implies a numeric count without specifying the return format or structure. With many sibling tools, it does not provide enough context for an agent to confidently select this tool over related ones.
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 0% and the sole parameter 'customHeaders' is not explained. The description adds no meaning beyond the schema, and for a generic parameter, even brief context would improve usability.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'number of critical firmware upgrades available across managed devices.' The inclusion of 'critical' differentiates it from siblings like 'getUpgradeOverviewTryBeta,' though it does not explicitly mention any sibling distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like 'getFirmwareUpgradePlan' or 'getUpgradeOverviewTryBeta.' No when-not or exclusions are provided, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose side effects, auth needs, or behavior. It mentions pagination but lacks details on rate limits, error handling, or behavior for invalid clientMac.
Agents need to know what a tool does to the world before 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 clearly conveys purpose and key return content. 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?
No output schema exists, but description omits pagination details (e.g., sorting, response format) and does not explain the customHeaders parameter's use. Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 6 parameters have descriptions in the schema (100% coverage), so description adds minimal extra meaning beyond listing return fields. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns per-client connection history with specific details like timestamps and traffic, but does not differentiate from sibling tools like listClientsPastConnections, which may have similar functionality.
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 getClient or listClientsActivity. Does not specify prerequisites or constraints for 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 present, and the description does not disclose behavioral traits such as read-only nature, potential side effects, or permission requirements. The simple 'Get' verb implies safety, but no explicit confirmation is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It contains no extraneous words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple getter with no output schema and rich sibling context, the description is adequate but minimal. It does not explain the return format or typical use, but the schema provides robust parameter documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 three parameters with descriptions, so baseline is 3. The tool description adds no additional parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the trunk setting for a specific AP. The verb 'Get' and resource 'trunk setting' are precise, and the tool's purpose is distinguishable from siblings like getApGeneralConfig or getApVlanConfig, though it does not elaborate on what 'trunk setting' entails.
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 any exclusions or context. The description lacks information about prerequisites or typical use cases, leaving the agent to infer 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 provided, so description must disclose behavioral traits. It only states the action and sorting, no mention of side effects, read-only nature, rate limits, or what is included in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence, no redundancy, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description does not explain what fields are returned (e.g., AP name, MAC, traffic volume). Agent cannot anticipate 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%, and schema already explains siteId well. Description adds no extra meaning about 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?
Description clearly specifies the action (get), resource (most active access points), context (in a site), and sorting (by traffic volume). It distinguishes 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?
No guidance on when to use this tool vs alternatives. Sibling tools exist for specific AP details (e.g., getApDetail), but the description does not help the agent choose.
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 must disclose behavioral traits. It mentions time-series data and trends but does not cover rate limits, data freshness, pagination, or read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, front-loaded with action and resource. Efficient and to the point.
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?
Adequate for a simple data retrieval tool with optional parameters. Lacks output format details but covers core functionality. No contradictions.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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, providing clear parameter details (siteId with defaults, customHeaders as optional). The description adds context about upload/download trends but does not enhance parameter meaning.
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 traffic activity time-series data for a site, focusing on upload/download trends. It is specific with verb+resource, but does not explicitly differentiate from siblings like getTrafficDistribution or getDashboardOverview.
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 implies usage for trend analysis, but does not mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavior. It only says 'Get available channels', omitting read-only nature, output format, side effects, or prerequisites beyond what schema implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no unnecessary words. Efficient for its length.
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. Fails to explain return structure or how to interpret 'available channels', leaving critical 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?
Schema description coverage is 100% with clear param descriptions (e.g., MAC format, site ID fallback). Description adds no extra meaning, but baseline of 3 is appropriate given 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?
Description states verb 'Get' and resource 'available channels for an AP', which is specific and distinct from sibling tools (e.g., getSitesApsBridge, getSitesApsChannelLimit). No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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. The schema hints at using listDevices for AP MACs, but descriptions do not clarify use cases 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, leaving the description as the sole source of behavioral disclosure. It only states the purpose without mentioning read-only nature, side effects, permissions, rate limits, or response structure. For a read operation, more context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the core purpose without unnecessary words. It is appropriately front-loaded and 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?
Despite a clear purpose, the description lacks completeness given the tool's context: no output schema, many sibling tools, and important details like default site behavior, response format, and prerequisites are missing. The agent would need to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 parameter meaning beyond what is already in the schema. It does not repeat or enhance 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 clearly states the action ('Get') and the specific resource ('OFDMA configuration for an AP'). It distinguishes from sibling tools like getSitesApsBridge or getApDetail by naming the exact configuration type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. The schema mentions using listDevices and listSites for parameter values, but the description itself lacks context for tool selection among many similar getSitesAps* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It correctly implies a read-only operation ('Get PIN setting') but omits details such as whether the PIN is sensitive, if authentication is required, or what happens if the gateway lacks a SIM/PIN. Minimal transparency beyond intent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that packs the essential verb, resource, and qualifier. No wasted words. Front-loaded with action. Ideal length 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?
Despite the tool's simplicity, the description is incomplete. No output schema exists, so the agent needs hints about return format (e.g., PIN value, masked string, or error if not applicable). The sibling list contains many tools, and more context about the PIN's role (e.g., SIM card management) would help disambiguate.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 tool description adds no parameter-specific information, but the schema itself fully documents all three parameters (siteId, gatewayMac, customHeaders) with clear descriptions. No additional value from description, but no deficit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 PIN setting for a gateway (LTE model)' clearly states the specific action (get PIN setting), the resource (gateway), and a critical constraint (LTE model). This distinguishes it from sibling tools like getGatewayDetail which retrieves general info.
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 (e.g., gateway must be LTE model) or conditions (e.g., when SIM PIN is relevant). No comparison to related tools like getSitesGatewaysGeneralConfig.
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 'Get cable test incremental results' but doesn't disclose what the results contain (e.g., format, pagination) or that it's a read-only operation. Lacks 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 sentence with no superfluous words. Front-loaded with the core action. Highly concise while still clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no explanation of what 'incremental results' means vs 'full results' (getCableTestFullResults). Lacks context about return values or relationship to sibling tools. Incomplete for a tool with 3 params and no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, providing clear explanations for siteId, switchMac, and customHeaders. The description adds minimal extra meaning beyond the schema (e.g., 'for a switch' aligns with switchMac). 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 'cable test incremental results for a switch.' It distinguishes from sibling tools like getCableTestFullResults (full vs incremental) and getCableTestLogs (logs vs results), and the switch-specific focus is evident.
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 like getCableTestFullResults or getCableTestLogs. No mention of prerequisites 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 provided, so the description carries the full burden of behavioral disclosure. It states 'most active' and 'sorted by traffic volume' but does not define the number of results, pagination, or response format. Critical behavioral traits like limit, ordering direction, or potential error conditions are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the tool's purpose. No extra words. However, it could benefit from front-loading key behavior like 'Returns a list of...' but it is still acceptably concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a complex dashboard tool. There is no output schema, and the description does not specify return values, limits, or field details. Given the lack of annotations and output schema, the agent lacks crucial information to correctly interpret the results.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 any parameter-specific meaning beyond what the schema already provides (siteId and customHeaders are well-described in the schema). No additional context is offered.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 that the tool retrieves the most active switches in a site, sorted by traffic volume. This distinguishes it from sibling tools like getDashboardMostActiveEaps which targets EAPs, and other dashboard tools that cover different metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. While the context of sibling tools implies it is for dashboard-level switch activity, there is no mention of when not to use it or which scenario favors another tool.
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 burden for behavioral disclosure. It only lists returned metrics without stating whether the operation is read-only, if authentication is required, or any rate limits. The parameter hint about default site ID is minimal. The lack of behavioral context limits the agent's ability to understand 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 17 words that efficiently lists the key metrics returned. Every word adds value; there is no redundant or extraneous information. It is front-loaded with the purpose and immediately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists the metrics (switch count, ports, PoE, bandwidth) which gives adequate context for a summary tool. However, it lacks behavioral details (read-only, rate limits) and return format (e.g., units, data types). For a tool with 0 required params and 2 optional ones, it is minimally complete but insufficient for an agent to fully understand invocation 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%, so the input schema already documents both parameters (siteId and customHeaders). The description does not add any additional meaning beyond what the schema provides; it omits mention of parameters entirely. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves a switch summary for a site dashboard, listing specific metrics: total switch count, total ports, active ports, PoE budget used vs available, and aggregate bandwidth. This distinctively scopes the tool as an aggregated summary, differentiating it from sibling tools like getSwitchDetail or getDashboardPoEUsage.
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 dashboard tools such as getDashboardMostActiveSwitches or getDashboardPoEUsage. There are no exclusions, prerequisites, or contextual hints about when this summary is appropriate, leaving the agent to infer usage solely from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must cover behavioral traits. It mentions pagination, time range, and search filtering, indicating a read operation. However, it does not disclose any side effects, authentication needs, or rate limits. The description 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 concise sentences, front-loaded with the core purpose and key features. No extraneous information; every sentence 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?
Given 9 parameters and no output schema, the description covers pagination, time range, and search, but lacks details on return structure or field names. The presence of many sibling tools suggests more differentiation could be helpful, but the description is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds overall context but does not enhance individual parameter meanings beyond the schema. It summarizes filtering options but does not provide additional semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool as retrieving a paginated list of historical known clients with optional time range and search filtering. However, it does not explicitly distinguish it from similar sibling tools like getGridClientHistory or listClientsPastConnections.
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 getClient, listClients, or getGridClientHistory. The description implies usage for historical clients but fails to provide when-not or explicit 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 carries full burden. It only indicates a read operation ('Get'), but lacks disclosure of behavioral traits such as idempotency, auth requirements, error conditions, 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 a single sentence of 7 words with no wasted content. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (get config) and no output schema exists. The description is minimal but adequate for a straightforward read operation. However, additional context about the bridge config format or related tools 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 description coverage is 100% with detailed parameter descriptions (e.g., apMac format, siteId default behavior). The tool description adds no additional parameter information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'P2P bridge config', and the scope 'for an AP'. It is specific and distinguishes from sibling tools that retrieve other configs (e.g., 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 explicit guidance on when to use this tool versus alternatives or when not to use it. The description is purely functional with no usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as pagination, rate limits, error conditions, or output structure. The simple read operation is implied but not explicitly described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 5 words, front-loaded with the action and resource. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the lack of an output schema and absence of description about the returned port information makes it minimally adequate. The description adds no context beyond the name.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 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 'List ports on an AP' clearly states the verb and resource, distinguishing it from similar sibling tools like getApDetail (AP details) and listSitesCableTestSwitchesPorts (switch ports).
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 or alternatives. The schema includes hints (e.g., 'Use listDevices to find AP MACs'), but this is not part of the description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as whether the operation is read-only, any side effects, or authentication requirements. The minimal phrase 'List ports' gives no behavioral insight beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of a single sentence that immediately conveys the purpose. Every word earns its place without superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not indicate what the response contains (e.g., port names, IDs). For a list operation, more detail on the output format would be helpful. The description is minimally adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's own parameter descriptions, which are already clear. Therefore, no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'ports available for cable test on a switch', which is specific and distinct from siblings like getCableTestFullResults and getCableTestLogs.
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. While the parameter schema includes references to other tools (listSites, listDevices), the description itself offers no usage context or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool is deprecated and that it filters the site device list in-process rather than being a dedicated API endpoint. Without annotations, this provides useful 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences pack deprecation warning, alternative, and purpose. The contradiction slightly harms clarity, but overall it is concise and front-loaded.
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 explain what data is returned, error handling, or how the in-process filtering works. The deprecation and contradictory purpose leave gaps for an agent to determine correct 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?
The input schema covers 67% of parameters with descriptions; deviceId lacks description. The description adds context about siteId defaulting but does not explain deviceId or customHeaders beyond the 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 the tool is deprecated and to use listDevices, but also claims to 'Fetch detailed information for a specific Omada device', which contradicts the earlier statement that no dedicated per-device endpoint exists. This muddles the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs users to use listDevices instead, providing clear guidance on when not to use this tool. However, it does not clarify when one might still want to use getDevice despite deprecation.
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. The verb 'Get' implies a read-only operation, but no explicit statement about non-modification, auth requirements, or rate limits is included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: first states purpose with included items, second provides a parameter hint. 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 exists, and description does not explain return format or structure. While it lists some included configuration items, it lacks completeness for a get tool that returns complex 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?
Schema provides full descriptions for all 3 parameters (siteId, switchMac, customHeaders) with 100% coverage. The description adds value beyond schema by suggesting use of listDevices for switchMac, improving semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves general configuration for a switch and lists included parameters. However, it does not explicitly differentiate from similar sibling tools like getSwitchDetail or getSitesSwitchesGeneralConfig.
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 a hint to use listDevices to obtain switchMac values, but offers no guidance on when to use this tool versus alternatives like getSwitchDetail or getSitesSwitchesGeneralConfig.
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 the function without mentioning read-only nature, required permissions, or side effects. The minimal description fails to inform an AI agent about safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no extraneous information. It is appropriately sized and front-loaded.
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 three parameters (one with no description), no output schema, and many sibling tools, the description is too brief. It does not specify what 'detailed information' includes, leaving the agent uncertain about the tool's 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 67%, with siteId and customHeaders having descriptions. The tool description adds no extra meaning beyond the schema; stackId lacks a description. Baseline is 3 due to moderate coverage, but no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches detailed information for a specific switch stack, using a specific verb and resource. It distinguishes from sibling tools like getStackPorts and getStackNetworkList by specifying it retrieves 'detailed information' rather than ports or networks.
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 getting stack details but provides no explicit guidance on when to use this tool versus alternatives, such as when to use getStackPorts or getStackNetworkList instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description only says 'List', which implies read-only, but does not disclose pagination behavior, ordering, error handling, or rate limits. The schema includes page and pageSize, but the description adds no behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with essential action and resource. 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?
No output schema exists. The description does not explain return values, error cases, or what information each stack entry contains (e.g., IDs, names, status). For a list tool with pagination, more context is needed 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?
Schema coverage is 100% with all 4 parameters described. The description does not mention parameters, but the schema already documents them. 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 'List switch stacks in a site.' clearly states the action (list) and resource (switch stacks) with a scope (site). It distinguishes from sibling tools like getSwitchStackDetail (detail of one stack) and getOswStackLagList (specific lag info).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing stacks but provides no guidance on when to use it vs. alternatives, when not to use it, or prerequisites like siteId behavior. The schema notes default site from config, but that is not in the description.
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 should disclose behavioral traits. It only describes what is returned, but omits that it is read-only, has no side effects, or any permission requirements. This leaves the agent with incomplete safety information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that convey the tool's output and optimal usage. 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 tool has no output schema, but the description sufficiently outlines the return structure (device counts, client counts, graph, health). It is fit for an overview tool, though it could mention if the data is real-time or cached.
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 descriptions for both parameters. The description adds value for siteId by explaining the default behavior and how to discover site IDs, which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a site overview topology with specific counts and health status. The phrase 'good first call' implies it's an entry point, but it doesn't explicitly differentiate from sibling tools like getDashboardMostActiveEaps.
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 suggests using it as a first call to understand the network, providing some context. However, it does not specify when not to use it or mention alternative tools for more detailed views.
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 states what data is returned but does not mention that the operation is read-only, any permissions required, or potential side effects. This is minimal transparency 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, well-structured sentence that front-loads the purpose and lists key output fields. Every word is meaningful; no wasted text.
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 lists the returned data points, it lacks details on the output format (e.g., JSON structure, data types) since there is no output schema. With nested objects implied, completeness is moderate; agent may need to infer exact 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 already describes both parameters (siteId and customHeaders). The description adds no additional meaning or usage hints 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 a WiFi summary for a site dashboard and lists specific data points (total APs, connected AP count, wireless client count, channel utilization per band, SSID count). It distinguishes from sibling tools like getDashboardSwitchSummary and getDashboardOverview by specifying 'WiFi' summary.
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 obtaining WiFi summary data, but provides no explicit guidance on when to use this tool versus alternatives like getApDetail for individual AP details. No exclusions or prerequisites 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?
No annotations are provided, so the description must disclose behavioral traits. It only states 'Returns a time-series of client counts' without detailing structure, side effects, rate limits, or data freshness. It does not mention if the operation is read-only or any other constraints.
Agents need to know what a tool does to the world before calling it. Descriptions 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 short sentences front-loaded with the main purpose and key requirement. No unnecessary words, and every sentence 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?
Without output schema, the description should explain return values more clearly. 'Returns a time-series of client counts' is vague; details on format, granularity, error handling, or timezone are missing. It meets minimum needs but is not complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description reiterates that start and end are Unix epoch seconds, adding no extra meaning beyond the schema. Baseline score of 3 applies as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves historical client count trend as a time-series, using specific verb 'Get' and resource. It distinguishes from siblings like getClient and listClients by focusing on aggregated trend data over time.
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 required parameters (start, end as Unix epoch seconds) but does not provide explicit when-to-use or alternatives. Usage is implied by the nature of historical trend, but no guidance on preferring this over similar tools like getGridClientHistory.
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 only states 'Get' implying read-only, but lacks details on permissions, error handling, or response structure. With no annotation support, this 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's purpose. It is front-loaded and efficient, though it could benefit from a brief mention of what the QoS configuration contains.
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 (3 parameters, no output schema), the description covers the basic functionality and parameter guidance. However, it does not describe the return format or structure of the QoS configuration, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 3 parameters have schema descriptions (100% coverage), and the tool description adds extra context such as how to obtain AP MACs and site IDs, default behavior for siteId, and example for customHeaders. This exceeds the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'QoS configuration' for a specific access point, differentiating it from sibling getAp* tools like getApDetail or getApGeneralConfig which focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives. However, parameter descriptions provide useful prerequisites like 'Use listDevices to find AP MACs' and 'Use listSites to discover available site IDs', offering some indirect 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 are provided, so the description carries full burden for behavioral disclosure. It does not mention side effects, read-only nature, permissions, or rate limits. While it implies a read operation, it lacks explicit 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 with no wasted words. It front-loads the purpose and includes a helpful prerequisite. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is fairly complete: it defines the returned data fields and provides a prerequisite. It could mention the return structure (e.g., per-radio object) but is still adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds the hint to use listDevices for apMac, but does not significantly add meaning beyond the schema 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 clearly states the tool retrieves radio status for a specific access point and lists the specific data points (band config, channel, TX power, etc.). It distinguishes from siblings like getApDetail or getRadiosConfig by specifying 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?
Provides a prerequisite ('Use listDevices to get the apMac') but does not explicitly state when to use this tool vs alternatives like getRadiosConfig or getApDetail. Usage context is implied but not fully defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the outputs but does not disclose whether the operation is read-only, any authentication requirements, rate limits, or side effects. The description is adequate for a simple read operation 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 three sentences, front-loaded with the core action, and contains no unnecessary words. Every sentence adds value, making it efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and three parameters, the description adequately covers what the tool returns (history, per-port results, cable length, fault detection). It is complete for the intended use case, though it omits potential issues like pagination or result limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 already described in the schema (e.g., siteId, switchMac, customHeaders). The description adds no additional semantic meaning beyond what the schema provides, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get cable test logs for a switch' and lists specific outputs (history, per-port results, cable length, fault detection), which clearly identifies the tool's purpose. However, it does not explicitly distinguish from the sibling 'getCableTestFullResults', which may return different results, but the name and description imply logs vs full results.
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 'useful for diagnosing physical layer connectivity issues,' giving context for use. However, it does not provide explicit guidance on when not to use this tool or mention alternatives like 'getCableTestFullResults'.
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 implies read-only operation but does not disclose behavioral traits like authentication needs, rate limits, or side effects. Minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose, no wasted words. Every element provides 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?
No output schema; description lists key return fields (signal strength, etc.), providing a reasonable mental model. Slightly incomplete but sufficient for a detail 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 covers all 3 parameters with full descriptions (100% coverage). Tool description adds no parameter-specific meaning beyond schema, but lists output fields, which indirectly helps. 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 verb 'Get', resource 'full detail for a specific client', method 'by MAC address', and lists included data (connection info, IP, VLAN, signal strength, traffic stats). Distinguishes from siblings like getClient (basic) and listClients (list).
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 vs alternatives like getClient or listClients. Does not mention prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the basic distribution. It lacks information about data sources, performance, or authentication requirements, 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 two concise sentences that front-load the purpose and usage. Every word earns its place with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no required parameters, no output schema, and simple semantics, the description is fairly complete. It explains the output (distribution by connection type and band) and its utility, leaving little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning the schema already documents both parameters. The description adds no additional meaning or context beyond the schema definitions, 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 ('Get') and resource ('client count distribution by connection type and band') and clearly distinguishes this tool from sibling tools like getClient, listClients, 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?
The description states it is 'useful for understanding the network composition at a glance,' which implies when to use, but does not provide explicit when-not or alternative tool recommendations. It stays at a basic level.
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. It only states the basic action without disclosing read-only nature, potential side effects, or rate limits. The brevity leaves the agent guessing about 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-retrieval tool with no output schema, the description is mostly adequate. It could briefly mention what the returned list contains (e.g., tag names/IDs), but the current minimalism still provides essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters documented. The tool description adds no extra meaning beyond the schema. Baseline of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get), the resource (device tags), and the scope (defined in a site). It distinguishes from sibling tools like getDevice or listDevices which deal with devices, not tags.
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 one needs device tags for a site, but provides no explicit guidance on when to use this tool vs alternatives like getDevice or listDevices. No when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the return values (current version, latest version, upgrade availability) but does not discuss authentication requirements, rate limits, error conditions, or any side effects. As a read-only tool, this is minimally adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no redundant information, and front-loads the primary purpose. 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?
For a simple single-device firmware info tool, the description covers the essential behavior and return data. However, it omits details on error scenarios (e.g., device not found) and does not address the output structure, though no output schema exists. Overall, it is largely complete given the tool's modest complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter already described in the schema. The description adds only a mention that listDevices can provide deviceMac values, which adds minimal semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves firmware information for a specific device, naming the returned fields (current version, latest, upgrade availability). It distinguishes from many sibling tools focused on firmware upgrade plans or lists, but does not explicitly differentiate from similar tools like getFirmwareUpgradePlan 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises using listDevices to obtain the required deviceMac, which is a helpful prerequisite. However, it provides no guidance on when to prefer this tool over alternatives, nor does it mention any conditions where this tool should not be used.
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 carry full burden. States 'Get' implying read-only, but no details on permissions, side effects, or idempotency. Adequate but minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence that front-loads the purpose. Concise without unnecessary words. Could benefit from additional context but efficient for its length.
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 no annotations, description adequately explains what the tool does. However, it does not describe the return value format or any error conditions. Sufficient for a simple getter but leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. Description adds no extra meaning 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?
Clearly states it retrieves the 802.1X switch port authentication setting. Distinguishes itself from sibling tools like getSwitchGeneralConfig by specifying the exact setting (802.1X) and purpose (port-based network access control).
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 versus alternatives. Sibling tools exist for other switch settings (e.g., getSwitchGeneralConfig), but description does not differentiate usage context. Agent must infer based on tool 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?
No annotations are provided, so the description must cover behavioral aspects. It correctly indicates a read operation and what is returned, but does not disclose potential side effects, authentication requirements, or rate limits. Basic transparency is achieved.
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 two sentences long, front-loading the purpose and then adding relevant detail. No superfluous words are present, making it 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 no output schema, the description explains what is returned (breakdown by category) but lacks detail on data structure (e.g., list vs object, time resolution). It is adequate but not fully complete for a tool with 4 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 description adds 'start and end are Unix timestamps in seconds', which reinforces the schema but adds little new meaning. 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', the resource 'traffic distribution', and explains it shows breakdown by protocol and application type (video, gaming, etc.). This distinguishes it from sibling tools like getClientsDistribution or 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 explicitly state when not to use it or mention alternative tools. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 disclosing behavioral traits. It only describes what is returned but does not mention whether the operation is read-only, has side effects, requires specific permissions, or has rate limits. For a tool returning network details, this lack of behavioral context is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource, and provides immediate value. Every sentence serves a purpose—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?
With no output schema, the description must convey the return structure. It lists key fields (switch, port, speed, PoE), which is adequate for a network topology tool, though lacking details like data types or example values. The moderate complexity and presence of 3 parameters are well-addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 three parameters documented via pattern, description, and defaults. The description adds no additional meaning beyond the schema (e.g., explaining the format of apMac or the fallback behavior of siteId is already in the schema). Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool gets wired uplink detail for an access point, specifying the resource (AP's Ethernet uplink) and the types of information returned (connected switch, port number, link speed, PoE status). This specific verb+resource combination distinguishes it from sibling tools like getApDetail or getApGeneralConfig, which cover broader AP information.
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 mapping physical network topology, implying a context, but does not explicitly state when to use this tool versus alternatives. No exclusions or when-not-to-use guidance is provided, leaving agents to infer usage from the tool's name and domain.
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 burden of behavioral disclosure. It describes the return data but does not mention traits like pagination, rate limits, or side effects. The description is straightforward for a read operation 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 two sentences, front-loading the action and return details, then offering context. Every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with 2 parameters and no output schema, the description is nearly complete. It states purpose, return data, and use cases. Minor omissions (e.g., pagination) do not significantly hinder utility.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 minimal parameter context beyond what the schema provides; it only implies siteId usage. No additional semantics are introduced.
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 all network clients connected to a site and enumerates returned fields. However, it does not explicitly differentiate from sibling tools like getClient or listClientsActivity, which reduces distinguishing clarity.
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 suggests using the tool for auditing or finding clients by name/MAC, but provides no explicit guidance on when to prefer alternatives or when not to use this tool. This leaves selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It states the return is 'top devices by memory usage' but omits details on ordering, limits, read-only status, or side effects. The lack of explicit read-only hint leaves 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?
Single sentence, front-loaded with action and resource, 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?
Given no output schema and no annotations, the description should provide more context on return format or behavior. It tells what the tool does but not the structure of the results (e.g., list of devices with memory percentages). Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no parameter-specific details beyond the schema, which already describes siteId and customHeaders 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 uses a specific verb ('Get') and resource ('top devices by memory usage for a site'), clearly distinguishing it from sibling tools like getDashboardTopCpuUsage.
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 implied usage ('useful for identifying memory-constrained devices') but no explicit when-to-use or when-not-to-use guidance, nor comparisons with alternatives like other dashboard 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, so the description must fully cover behavioral traits. It describes what data is returned but does not disclose whether the tool is read-only, any potential side effects, authentication requirements, or rate limits. This is inadequate for safe agent invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences, no fluff, front-loaded with the action and output. Every sentence adds value, aligning with best practices for tool descriptions.
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 lists the key return data (link quality, signal strength, throughput, hop count) but does not specify the output structure or format. With no output schema, additional detail about the return shape 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 provides 100% coverage with descriptions for each parameter, including examples and references. The tool description adds no additional parameter-level detail beyond what the schema already provides, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 mesh link statistics for an access point, specifically returning quality, strength, throughput, and hop count. This distinguishes it from sibling tools that provide general AP details or other specific configurations, as none explicitly target mesh statistics.
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 indicates the tool is 'useful for diagnosing mesh network performance,' providing a clear use case. However, it does not explicitly state when not to use this tool or mention alternative tools, though no direct alternative exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the core behavior (returns VLAN assignments per port) but lacks details on side effects, authentication, or rate limits. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose, and a concise usage tip. 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?
No output schema; description explains what is returned but not the structure. For a list tool with moderate complexity, some additional detail about response format 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 description coverage is 100%, and the description adds no new parameter information beyond what is already in the schema. The tip about listDevices is redundant with the schema's switchMac 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?
Description clearly states the tool lists VLAN network assignments for a switch, specifying it returns which VLANs are assigned to which ports with tagged/untagged config. This distinguishes it from siblings like getSwitchDetail or getSwitchGeneralConfig.
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?
Provides a helpful hint to use listDevices to get switchMac values, but does not discuss when to use this tool over alternatives or when not to use it. Limited guidance on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns all devices including offline/disconnected, which is helpful. But it lacks details on permissions, rate limits, pagination, or return format, which are important for agent decision-making.
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?
Two sentences, clear and front-loaded. No unnecessary words, but slightly more structure could improve scanability.
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 provides purpose and differentiation from a sibling, but lacks details on return values, pagination, or output format. Given no output schema, the agent may need more information to handle the response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters beyond what the schema provides. It mentions 'siteId' implicitly but no parameter-specific elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 gets all devices in a site, including offline and disconnected devices, and explicitly distinguishes it from listDevices which may filter to active-only. This provides a specific verb+resource with clear differentiation from siblings.
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 indicates when to use this tool (for full inventory auditing) and contrasts with listDevices. However, it does not explicitly state when not to use it or provide alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description bears full burden. It describes the fetched data (model, firmware, etc.) but does not explicitly state the operation is read-only, nor does it mention side effects, prerequisites beyond apMac discovery, or rate limits. The term 'Fetch' implies reading, but the behavioral context 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 covering the essential return fields and a key prerequisite. Every word serves a purpose. 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 absence of an output schema, the description lists specific return attributes (model, firmware, CPU/memory, clients, SSIDs, uptime, mesh status), offering a good picture of what to expect. However, it lacks details on the output structure (e.g., nested object) and does not mention error handling or missing data scenarios. Still, it is reasonably complete for a 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 description coverage is 100%, with each parameter already well-documented. The description text does not add new parameter semantics; it only lists return attributes. Thus, no added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it fetches full configuration and status for a specific access point, listing specific attributes. This differentiates it from sibling getAp* tools that cover individual sub-configurations. Also advises to use listDevices to obtain the apMac, making 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 only usage guidance is to use listDevices to get the apMac. There is no explicit mention of when to use this tool versus the many sibling tools for specific AP configurations. The implication is that it's for a comprehensive overview, but no alternatives or when-not-to-use are discussed.
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 cover behavioral traits. It states read-only nature ('Get') and returns data, but lacks details on auth, rate limits, or what happens if AP doesn't support LLDP. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, output summary, background. Front-loaded with key info, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema and moderate complexity, description covers what it returns. Missing error conditions or references to listDevices for apMac, but generally 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%, so description adds no extra parameter meaning. The mention of return value ('enabled state and advertised TLVs') is not parameter-specific. Baseline score 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?
Clear verb ('Get'), specific resource ('LLDP configuration for an access point'), and output ('enabled state and advertised TLVs'). Distinct from sibling tools which target other AP configuration aspects.
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 vs alternatives (e.g., getApGeneralConfig). Siblings all different but no differentiation provided. Implied from name only.
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 states the output includes cable status, length, and fault location, but does not mention permission requirements, resource implications, or any side effects. It is insufficient 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 two sentences with no wasted words. The first sentence states the core purpose, the second provides detail and differentiation from a sibling. 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?
Without an output schema, the description explains key return fields (cable status, length, fault location) and is relevant for a tool with only one required parameter. However, it does not describe pagination, limits, or other edge cases, leaving minor 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?
All three parameters have clear descriptions in the input schema (100% 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 returns 'full cable test results for all ports on a switch' and explicitly distinguishes itself from the sibling 'getCableTestLogs' 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 provides clear context for use (detailed per-port diagnostics) and contrasts with the sibling tool, but does not mention when not to use it or other alternatives beyond the one sibling.
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 adequately describes the tool as a read operation ('Get') and lists returned data, but does not explicitly state that it is non-destructive or mention any rate limits or side effects. Adequate for a read-only 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 concise sentences, no irrelevant information. Key features are front-loaded. 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?
With 9 parameters, no output schema, and no annotations, the description covers the tool's purpose, key features, and return fields (timestamps, traffic, duration, device details). It could be slightly more complete by noting pagination defaults from schema, 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 description coverage is 89%, so parameters already have descriptions. The description adds a summary of supported operations (pagination, filtering, etc.) but does not provide significant additional semantics beyond the schema. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get client past connection list with historical connection data' and lists specific returned fields (timestamps, traffic, duration, device details). It distinguishes from sibling tools like 'listClients' (likely current clients) and 'getClientDetail' (individual details) by focusing on historical connections.
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 supported features (pagination, filtering, sorting, search) but does not explicitly state when to use this tool versus alternatives like 'listClients' or 'getClientHistory'. Usage context is implied but not clearly delineated.
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 discloses the tool is read-only (Get) and describes the returned fields and sorting. However, it omits information on authorization needs, rate limits, or whether any state changes occur, which are essential for behavioral 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 concise sentences plus a clarifying third sentence. It is front-loaded with the action and output, and every sentence adds value. 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?
The description covers purpose, parameters, and return fields adequately. However, it does not specify limits like the number of clients returned (e.g., top 10), which is a gap for a 'most active' query. With no output schema and many sibling tools, this information would help the agent understand the scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 both parameters (siteId, customHeaders) with descriptions. The description does not add parameter-specific details beyond the schema, but the schema descriptions are clear (e.g., siteId fallback to default). With 100% schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the most active clients in a site, sorted by total traffic.' It specifies the verb (Get), the resource (most active clients), and the scope (in a site, sorted by total traffic). This distinguishes it from sibling tools like listClients which would list all clients without sorting by traffic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description labels it as a 'dashboard endpoint' providing a 'quick overview', implying a use case but not explicitly stating when to use it over alternatives. No exclusions or when-not-to-use guidance are provided, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists returned fields (device type, MAC, IP, model) but lacks details on read-only nature, pagination, or prerequisites. Without annotations, the burden is higher, and this is only partially met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, with the purpose front-loaded and no extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with few parameters and no output schema. The description covers purpose and return fields adequately, but could add context about typical use or read-only behavior for 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 description adds no additional meaning beyond the schema. Both parameters are fully documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists devices discovered but not adopted, distinguishing it from other list tools. It specifies the verb (list), resource (pending devices), and provides context (waiting to be provisioned).
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 viewing devices awaiting adoption but does not explicitly state when not to use or compare with sibling tools like listDevices or searchDevices.
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 provided, the description carries the burden of behavioral disclosure. It clearly indicates a read-only operation ('Get', 'Returns configured...') and describes the output. It does not mention potential side effects, rate limits, or permissions, but for a simple read tool this is adequate. The description is transparent about the action and result.
Agents need to know what a tool does to the world before calling it. 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 concise sentences. The first sentence states the purpose and return content, the second provides a critical prerequisite. No extraneous words or repetition; every sentence 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?
Given no output schema, the description offers a high-level overview of returned fields (member ports, load balancing mode, status) but lacks details on the response structure, pagination, error cases, or additional considerations. It is adequate for a simple list tool but incomplete for an agent to fully handle edge cases or parse 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?
Schema description coverage is 100%, so the baseline is 3. The description does not add new information beyond the schema; it repeats the prerequisite for stackId already in the schema. No additional parameter details are provided that would enrich the agent's understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Get', the resource 'Link Aggregation Group (LAG) list', and the target 'switch stack'. It specifies the returned data (member ports, load balancing mode, status), clearly distinguishing it from sibling tools like getStackPorts or getStackNetworkList.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite (use getSwitchStackDetail to get stackId) but does not explicitly state when to use this tool versus alternatives like getStackPorts or getStackNetworkList. The usage context is implied by the tool's name and description but lacks explicit guidance on 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 exist, so the description must carry full burden. It indicates a read operation ('Get') but does not detail any potential side effects, required permissions, or idempotency. 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?
Two sentences directly convey the action and use case. No extraneous information; every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description lists key return fields, which is helpful. It omits details like pagination or single-AP scope, but given the simplicity of the tool, the description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions. The tool description adds no additional parameter semantics beyond what is already in the schema, achieving the baseline for 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves SNMP configuration for an access point and lists specific returned data. It distinguishes itself from siblings like getApGeneralConfig or getApRadios by focusing on SNMP-specific settings.
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 places the tool in the context of auditing SNMP-based monitoring, guiding use. However, it does not explicitly mention when to avoid this tool or suggest alternatives, though the sibling context makes differentiation plausible.
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 indicates it is a read operation (name and phrase 'Returns...') but does not explicitly state lack of side effects or disclosure of any behavioral traits beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-loading the purpose and then a brief usage hint. 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?
Lacks output schema but description sufficiently lists what is returned. With no annotations, it still provides enough for a simple read tool. Could mention read-only nature explicitly.
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 descriptions for each parameter. The description adds value by advising 'Use listDevices to find AP MACs' for apMac and notes default behavior for siteId. No added meaning for customHeaders.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 verb 'Get' and the resource 'uplink configuration for an access point', and lists specific returned fields (uplink mode, preferred uplink settings, failover configuration). This distinguishes it from sibling AP configuration tools like 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?
Provides a usage context ('useful for understanding mesh topology and wired uplink assignments') but does not explicitly state when to use versus alternatives, or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'Returns the AP's management VLAN and per-SSID VLAN tagging settings', indicating it's a read operation. But it does not disclose any prerequisites, error conditions, or additional 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the core action and resource, followed by a use case. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a get tool with no output schema, the description adequately explains what data is returned (management VLAN and per-SSID VLAN). It does not cover error handling or default behavior for optional parameters, but the schema already handles parameter details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all parameters already described. The description adds no extra meaning to 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 'Get VLAN configuration for an access point', specifying the exact verb and resource. It distinguishes from siblings by focusing on VLANs, with other sibling tools like getApGeneralConfig or getApDetail covering different 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 mentions 'Useful for verifying network segmentation on wireless infrastructure', giving a clear context. However, it does not explicitly state when not to use or mention alternative tools among the many 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?
With no annotations provided, the description carries the full burden. It reveals that the tool 'filters the site client list in-process to emulate a per-client lookup,' disclosing an implementation detail. However, it does not mention error handling, permissions, or response format, leaving gaps in behavioral 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 extremely concise: three sentences, no wasted words. It front-loades the deprecation warning and alternatives, then states the core function. Every sentence 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, so the description should explain what 'details' are returned, but it only says 'Fetch details' without specifics. It also omits information about the required clientId parameter's format. Given the complexity (3 params, no output schema), the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (two of three parameters have descriptions). The description does not add significant meaning beyond the schema; it hints that clientId might be a MAC address by referencing getClientDetail, but does not clarify it explicitly. Baseline 3 applies due to moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Fetch details for a specific Omada client.' It also distinguishes from siblings by explicitly recommending listClients and getClientDetail as alternatives, making the specific use case unambiguous.
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 strong usage guidance by labeling the tool as '[DEPRECATED]' and directing users to 'Use listClients instead' and 'getClientDetail is also available' when a client MAC is available. This explicitly tells when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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 correctly indicates a read operation ('Fetch') and lists the data fields returned, but does not explicitly state that the tool is non-destructive, nor does it mention error conditions, authentication requirements, or rate limits. The description is 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 concise with only two sentences. The first sentence front-loads the core purpose and details, and the second provides an actionable instruction. No redundant or irrelevant information is present.
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 3 parameters and no output schema, the description sufficiently states what the tool returns (a list of configuration and status fields) and the prerequisite for the required parameter. However, it could be improved by mentioning the return format (e.g., JSON structure) or default behavior when 'siteId' is omitted, as the schema notes a default site.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 some context for the 'gatewayMac' parameter by directing users to listDevices, but does not provide additional semantic information for 'siteId' or 'customHeaders' beyond what the schema already includes. Minimal value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and explicitly lists the resources returned (model, firmware, CPU/memory, WAN/LAN ports, routing mode, feature flags), making the tool's purpose clear. It also distinguishes from sibling tools like listDevices by instructing to use that tool to obtain the required parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on how to obtain the required 'gatewayMac' parameter ('Use listDevices to get the gatewayMac'), which serves as a prerequisite. However, it does not explicitly state when to use this tool versus alternatives such as getApDetail or getSwitchDetail, though the name and scope imply it is for gateways.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It indicates a read operation ("Get") and lists output fields, but does not disclose potential behaviors like pagination, rate limits, or authentication scope. It is adequate 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?
The description is three concise sentences with no redundancy: the first states the core purpose, the second contrasts with siblings, and the third provides 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?
Given the lack of an output schema, the description compensates well by listing many output fields (link status, speed, IP, bytes in/out, port profile). It is complete enough for the agent to understand what the tool returns, though it could mention that it returns multiple ports.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 fully documents parameters. The description adds minimal extra meaning beyond referencing the gateway parameter and the prerequisite, but that is consistent with baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 all WAN and LAN port details (link status, speed, IP, bytes, port profile) for a specific gateway, and explicitly distinguishes itself from getGatewayWanStatus and getGatewayLanStatus, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool (more detailed alternative to sibling WAN/LAN status tools) and a prerequisite (use listDevices to get gatewayMac). It does not explicitly exclude use cases, but the guidance is clear and helpful for agent decision-making.
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 cover behavioral traits. It implies a read-only operation (getting a list), but it does not disclose any potential side effects, authentication requirements, or rate limits. 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?
The description is concise with two sentences: the first clearly states the action and resource, the second provides usage context. Every sentence adds value, and it is well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (many sibling tools, three parameters, no output schema), the description effectively explains what the tool returns (a list of scheduled firmware upgrade checks) and its utility. It is complete enough for an agent to decide when to use it, though more detail on the output structure could be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 67% of parameters with descriptions for 'page' and 'pageSize' (defaults and ranges). The description does not add additional meaning beyond what the schema provides. The remaining parameter 'customHeaders' is described in the schema but not in the description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the auto-check upgrade plan list showing scheduled firmware upgrade checks across devices.' It specifies the resource and action, and the additional sentence provides context for auditing and identifying devices due for updates, which distinguishes it from sibling tools like getFirmwareUpgradePlan.
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 advises when to use the tool: 'Useful for auditing upgrade schedules and identifying devices due for automatic firmware updates.' While it does not explicitly mention when not to use it or provide alternatives, the guidance is clear and contextually appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read-only operation but does not disclose potential side effects or API-specific behaviors (e.g., authentication, 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 three sentences, front-loaded with the core purpose, and contains no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately hints at the return (traffic volume and utilization per uplink). It is complete enough for a simple data 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 coverage is 100%, so baseline is 3. The description adds no significant meaning beyond what the schema provides; it reiterates that start and end are Unix timestamps, which is already in the property 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 clearly states a specific verb ('Get') and resource ('per-WAN ISP link load over a time range'), and differentiates it from sibling tools that focus on APs, switches, or clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context ('understanding load balancing behaviour, identifying saturated WAN links, and analysing failover events') but does not explicitly mention when not to use it or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns stored (not fresh) results and is deprecated. It does not cover permissions, error conditions, or rate limits, but it provides key behavioral information for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first announces deprecation and purpose, the second adds prerequisite and return data context. Every word is necessary; no redundancy. Front-loaded with the most critical 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?
Without an output schema, the description lists the data categories returned (neighboring networks, utilization, interference, RSSI). It also explains the prerequisite flow. It lacks details on empty results or error states, but for a straightforward retrieval tool with 3 well-documented parameters, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with clear descriptions for apMac, siteId, and customHeaders. The description adds no extra parameter semantics beyond the prerequisite mention of triggerRfScan, which is not parameter-specific. 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 the last RF scan results for an access point, a specific verb+resource. It lists the data types returned (neighboring networks, channel utilization, interference, RSSI). The name itself distinguishes it from sibling tools like getApDetail or getApRadios.
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 deprecates the tool, warns users, and provides a prerequisite: use triggerRfScan first to get fresh results. This gives clear usage context. It does not, however, mention alternatives for the deprecated endpoint 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?
The description implies a read-only operation but provides no explicit behavioral traits beyond the obvious 'Get' nature. With no annotations, the description carries the full burden; it lacks details like pagination behavior (though schema shows page/pageSize), performance impact, or authorization requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose plus one short tip. Every word adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return (VLAN interface assignments across all stack members) sufficiently. It covers the key outcome, though more detail on return structure could be helpful. Overall adequate for a list tool with well-documented parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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-defined in the schema. The description adds minimal extra meaning; it only reiterates that stackId comes from getSwitchStackDetail. Baseline of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the VLAN network list for a switch stack, specifying it returns VLAN interface assignments across all stack members. This distinguishes it from sibling tools like getSwitchDetail or listSwitchNetworks by focusing on stack-specific VLANs.
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 clear prerequisite: 'Use getSwitchStackDetail to get the stackId.' This instructs the agent on obtaining the required parameter. However, it does not mention when to choose this tool over alternatives like listSwitchNetworks, 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool is read-only and returns time-series data, but does not address permissions, pagination, or the meaning of 'time snapshot' beyond the parameters. More detail on the behavior would improve 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 with no wasted words. The first sentence states the core action and output, the second adds usefulness. It is 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 provides a good overview of the return structure (time-series with new, active, disconnected clients). However, it omits details like the time unit of snapshots or any pagination, leaving some gaps for a comprehensive 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?
The input schema already describes 3 of 4 parameters (75% coverage). The description adds the concept of 'time snapshot' but does not link it to the start/end parameters or explain defaults if omitted. Since schema coverage is high, the description adds marginal value, scoring a 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?
The description uses a specific verb ('Get') and resource ('client activity statistics'), clearly indicating it returns time-series data for client trends. It distinguishes from siblings by specifying 'over time' and including both wireless and wired clients, setting it apart from tools like 'listClients' or 'getDashboardTrafficActivities'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is 'useful for monitoring client connection trends and activity patterns', providing clear context for when to use the tool. However, it does not explicitly mention when not to use it or list alternative tools, missing a chance to fully guide 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 indicates a search operation but does not explicitly state if it is read-only, or describe behavior regarding empty results, pagination, or performance. The description is adequate but could add more 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 with no wasted words. The purpose and behavior are front-loaded. 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?
The tool is simple (search by key, returns devices). The description adequately explains global scope. Without an output schema, it would be helpful to mention the structure of returned devices, but for a basic search tool, this is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage). The description explains that 'searchKey' is the key to match, adding meaning. However, the 'customHeaders' parameter is not explained. The description partially compensates for low coverage but is not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 scope 'globally across all sites'. It also indicates the output ('Returns devices matching the search key'). This distinguishes it from siblings like 'getDevice' (specific device) and 'listDevices' (likely lists all devices without search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by specifying 'globally across all sites', implying it is for cross-site searching. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling list offers many specific getter tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies read-only behavior and lists returned values, but does not disclose potential side effects or authentication requirements. Sufficient 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?
Two concise sentences: first defines purpose and output, second gives prerequisite. No superfluous 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?
No output schema, but description lists key return fields. Mentions 'each WAN port' hinting at structure. Could elaborate on response format but adequate for selection.
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 descriptions. Description adds context like default site behavior and how to discover values (listDevices, listSites), going beyond schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 WAN port status and connectivity information for a specific gateway' and lists returned fields (WAN IP, DNS, etc.). Differentiates from sibling tools like getGatewayLanStatus.
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?
Provides prerequisite 'Use listDevices to find the gatewayMac'. Lacks explicit when-not-to-use or comparison with related tools like getGatewayDetail or getGatewayLanStatus.
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 what data is returned but does not explicitly state that the operation is safe/read-only, nor does it mention rate limits, auth needs, or side effects. The description is adequate but lacks behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no extraneous words. The first sentence lists all returned fields concisely, and the second provides a critical usage hint. Every sentence is valuable.
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 3 parameters and no output schema, the description provides adequate context: explains both required and optional parameters, mentions expected data returned, and gives a usage pointer. It lacks an explicit note about the output format but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default behavior of siteId (fallback to OMADA_SITE_ID), how to obtain switchMac (from listDevices), and that customHeaders is rarely needed. This exceeds the schema 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 clearly states it fetches full configuration and status for a specific switch, listing specific data (model, firmware, CPU, etc.). It distinguishes itself from sibling tools like getApDetail (for APs) and getSwitchGeneralConfig (only general config).
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 mentions using listDevices to get the switchMac, providing a prerequisite. It implies correct usage context (for a specific switch's full detail) but does not explicitly contrast with more specific sibling tools like getSwitchDot1xSetting or getSwitchGeneralConfig.
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 declares returned fields but does not disclose potential pagination, rate limits, or any side effects. For a read-only list tool, this is adequate but not comprehensive. Missing details like whether the list is always exhaustive or limited by page size.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. Front-loaded with purpose, then return fields, then usage guidance. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description explicitly lists all returned fields (MAC, model, firmware, IP, uptime, CPU/memory, status). That's sufficient for the agent to understand what to expect. Could mention if results are paginated, but overall complete for a list 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 already covers siteId with description linking to listSites. Description adds value by clarifying default behavior ('uses default site from OMADA_SITE_ID config') and noting customHeaders is 'Rarely needed.' This enriches the agent's understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description starts with specific verb 'List all provisioned (adopted) network devices in a site: gateways, switches, and access points.' It clearly states the resource and scope, and distinguishes from siblings like getAllDeviceBySite by emphasizing it returns a list with specific fields for provisioned devices.
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 guides the agent to use MAC addresses from this response as input to detail tools (getGatewayDetail, getSwitchDetail, getApDetail). This provides clear post-invocation context. However, it does not explicitly state when not to use this tool or compare to alternatives like searchDevices.
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 the tool returns stored configuration (not runtime status), which is a key behavioral trait. However, it does not mention whether the operation is read-only, if any side effects exist, or rate limits. Adequate 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?
The description consists of two concise sentences that immediately state the purpose and differentiate from a sibling tool. No unnecessary words; every sentence adds value. Ideal length for an AI agent.
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 output schema, the description compensates by listing example return fields. It references sibling tools for parameter discovery. For a simple configuration retrieval tool with three parameters, the description is nearly complete. Could mention pagination or rate limits, but these are unlikely to be relevant here.
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?
Schema coverage is 100% with detailed descriptions for all three parameters. The description adds external references (e.g., 'Use listDevices to find AP MACs', 'Use listSites to discover available site IDs') that significantly enhance parameter understanding. This goes well 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?
The description clearly states 'Get general configuration for an access point' and enumerates the returned fields (device name, LED settings, country/region, etc.). It explicitly distinguishes from sibling tool getApDetail by noting 'this returns stored configuration' vs runtime status. Purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: 'Use getApDetail for runtime status; this returns stored configuration.' This helps the agent choose between the two tools. However, it does not list other alternatives or explicitly state when not to use the tool. Overall, good context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It clearly states the tool returns a list of devices with MAC addresses and connection details, indicating a read-only retrieval. It lacks mention of potential errors, permissions, or rate limits, but for a simple get operation, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: first defines purpose, second describes output, third gives usage context. No extraneous words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no output schema, 3 parameters), the description covers purpose, output (list of devices with details), and usage context (APs with LAN ports). It is complete for effective agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameter descriptions are detailed (e.g., apMac with format, siteId with config reference). The description adds minimal parameter-specific value beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get wired downlink devices' and the resource 'connected to an access point's LAN port', distinguishing it from sibling tools that focus on uplinks, general device info, 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 provides context by noting it is useful for APs with built-in switch ports (e.g., EAP615-Wall), implying when to use. It does not explicitly exclude other scenarios or compare to alternatives, but the specificity is adequate.
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 explicitly lists the information returned (link state, speed, duplex, connected device, VLAN). This is a read operation and the description implies no side effects. It could be improved by stating it is read-only or mentioning rate limits, but is still transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences: the first states the tool's purpose and output fields; the second gives a necessary prerequisite. Every word is useful, no redundancy. Ideal structure for quick parsing.
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 return fields (port link state, speed, duplex, connected device, VLAN assignment). With three parameters (one required) and no output schema, the description adequately covers the tool's behavior and data scope.
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% for all parameters. The description adds value beyond the schema by providing actionable guidance: 'Use listDevices to get the gatewayMac.' This contextual hint helps the agent correctly supply 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 states 'Get LAN port status for a specific gateway: port link state, speed, duplex, connected device, and VLAN assignment.' It uses a specific verb ('Get') and resource ('LAN port status for gateway'), and the detail about returned fields distinguishes it from sibling tools like getGatewayWanStatus or getGatewayPorts.
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 prerequisite: 'Use listDevices to get the gatewayMac.' This guides the agent on parameter acquisition. While it doesn't explicitly state when-not-to-use or name alternatives, the specificity of the purpose makes it unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states what the tool returns but does not explicitly disclose behavioral traits such as read-only nature, permission requirements, or potential side effects. The verb 'get' implies a safe read operation, but the description could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no wasted words. The first sentence states the purpose, and the second provides the key differentiation with the sibling tool. It is 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 the fields returned (band, channel, transmit power, etc.) and provides context on parameters. Without an output schema, it does a good job describing what to expect. It could add details on error handling or output structure, but it is adequate for a simple configuration retrieval.
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%, and the description adds valuable context beyond the schema: for apMac it suggests using listDevices, and for siteId it explains default behavior and suggests listSites. This enhances the semantics beyond the raw 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 'per-radio configuration for an access point', and explicitly distinguishes it from the sibling tool getApRadios by specifying that this returns configuration while getApRadios returns 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus the alternative getApRadios, stating 'Use getApRadios for runtime radio status; this returns configuration.' This clearly differentiates the use case.
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 must fully disclose behavior. It states the tool returns upload/download throughput from the most recent speed test, implying read-only operation. Could mention empty results if no test done, but adequate for a simple getter.
Agents need to know what a tool does to the world before 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 explains prerequisite workflow. No redundancy, front-loaded with key 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?
No output schema, but description mentions return type (upload/download throughput). Lacks details on format or empty results, but given low complexity and clear prerequisite, it's mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds value by explaining apMac format and how to find it, siteId default behavior, and customHeaders rarity. Baseline 3, extra context justifies 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves last speed test results for an access point, specifying the resource (access point) and action (get results). It distinguishes from siblings like getCableTestFullResults by focusing on speed test throughput.
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 advises to use triggerSpeedTest first to initiate a new test, clarifying that this tool returns stored results. This provides clear when-to-use and 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.

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:

[![tplink-omada-mcp MCP server](https://glama.ai/mcp/servers/MiguelTVMS/tplink-omada-mcp/badges/card.svg)](https://glama.ai/mcp/servers/MiguelTVMS/tplink-omada-mcp)

Score Badge

Copy to your README.md:

[![tplink-omada-mcp MCP server](https://glama.ai/mcp/servers/MiguelTVMS/tplink-omada-mcp/badges/score.svg)](https://glama.ai/mcp/servers/MiguelTVMS/tplink-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/MiguelTVMS/tplink-omada-mcp'

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