TP-Link Omada MCP server

Server Quality Checklist

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

Latest release: v0.15.0
Disambiguation5/5
Each tool targets a specific resource and aspect (e.g., AP radios, VLAN config, cable test logs), with clear descriptions that differentiate even similar tools. Deprecated tools are explicitly marked, reducing ambiguity.
Naming Consistency5/5
Tool names follow a consistent verb_noun snake_case pattern (e.g., getApDetail, listDevices, getDashboardOverview). Verbs like 'get', 'list', 'search', 'trigger' are used predictably, with minor exceptions that do not hinder coherence.
Tool Count2/5
With 84 tools, the server is overpopulated for an MCP context. While the domain (network management) can be complex, the number far exceeds typical well-scoped sets (3-15), making it unwieldy for an agent to navigate effectively.
Completeness2/5
The tool set is heavily read-only, lacking any create, update, or delete operations for configurations. This is a significant gap for a management server, as agents cannot perform essential lifecycle tasks beyond retrieving data and triggering a few actions.
Average 3.5/5 across 84 of 84 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 1 commit in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden. It states 'Get' implying a read-only operation, but does not disclose whether there are side effects, permissions required, or any nuances about the 'try-beta' status. The minimal description leaves significant behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence (10 words) and is front-loaded. However, it is under-specified, so conciseness comes at the cost of completeness. Avoids verbosity but lacks necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and only a vague description, the tool is incomplete. An agent cannot infer the return format or how 'try-beta switch status' relates to firmware upgrades. The presence of similar sibling tools increases the need for more context, which is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, customHeaders, is not mentioned in the description. Schema description coverage is 0%, and the description adds no meaning beyond the schema definition. This fails to help the agent understand how to use or why to set 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 verb 'Get' and the resource 'try-beta firmware switch status for the controller,' distinguishing it from sibling tools like getUpgradeOverviewCritical. However, the term 'switch status' is vague and does not clarify whether it returns a boolean, state string, or configuration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as getFirmwareInfo, getUpgradeLogs, or getUpgradeOverviewCritical. The description lacks any context for when to invoke this specific 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?
No annotations are provided. The description does not disclose whether the tool is read-only, destructive, or has any side effects. While 'list' implies reading, the agent has no explicit confirmation. No information about authorization, rate limits, or other 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure. It does not front-load key behavioral information or provide any sectioning. It is efficient but not particularly helpful.
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 output schema and annotations, the description is insufficient. It does not clarify what 'firmware pool entries' are, nor how this tool differs from other firmware-related sibling tools. The complexity is moderate, but the description leaves many gaps.
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 beyond the input schema. Two of three parameters (page, pageSize) have schema descriptions already, but customHeaders is undocumented. The tool description does not explain the meaning of 'firmware pool entries' or how parameters affect results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'list' and the resource 'firmware pool entries in the upgrade overview', making it clear what the tool does. However, it does not differentiate from the sibling tool 'listUpgradeFirmwares', which could cause confusion. The specificity is good but could be improved.
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 its siblings (e.g., 'listUpgradeFirmwares' or 'getFirmwareInfo'). There is no mention of preferred contexts or prerequisites. The description is purely declarative.
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 all behavioral traits. It only states the tool searches and returns matching devices, omitting details like search algorithm, case sensitivity, pagination, result limits, or side effects. This is insufficient for a global search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, using two efficient sentences. However, the brevity sacrifices critical details needed for proper tool invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (2 parameters, nested objects, no annotations, no output schema), the description lacks completeness. It does not cover output format, error handling, or usage constraints, making it insufficient for an AI agent to use reliably.
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 description coverage is 0%, so the description must clarify parameter meanings. It only mentions 'search key' without specifying what constitutes a valid key (e.g., name, MAC, partial match). The 'customHeaders' parameter is completely 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 clearly states the tool searches for devices globally across all sites, which is a distinct purpose. However, it does not explicitly contrast with sibling tools like listDevices, which could also list devices across sites.
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 listDevices or getDevice. No when-not-to or context 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?
No annotations provided, so the description must disclose behavior. It only says 'list', implying a safe read, but omits details about pagination limits, authentication needs, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but minimally informative. It could be slightly expanded to include key details without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no output schema, the description is basic. It lacks context about return format, filtering, or ordering. Still, it covers the core purpose.
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%, but the description adds no extra meaning to the parameters (page, pageSize, customHeaders). The customHeaders object lacks explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'uploaded firmware files', indicating a read operation. It implicitly distinguishes from siblings like getFirmwareInfo or getFirmwareUpgradePlan by focusing on the list of available files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, filters, 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 discloses that the tool is deprecated and that no dedicated per-device endpoint exists in the spec, which provides some behavioral context. However, with no annotations provided, it lacks details on side effects, safety, or what happens when the device is not found.
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 short with two sentences, no redundancy, and the deprecation warning is front-loaded. It is efficient but could be more structured by separating the deprecation from the functional description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and nested objects, the description is too brief. It does not explain the return value format, behavior when the device is not found, or how the 'filtering' works. More context is needed for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, so the schema already documents two of three parameters (siteId, customHeaders). The description adds no additional meaning for the required deviceId parameter, which remains underdocumented. Score at baseline as description does not compensate.
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 is self-contradictory: it first says 'Filters the site device list in-process' implying a list, then says 'Fetch detailed information for a specific Omada device' implying a single item. The purpose is vague and confusing, especially with the deprecation note to use listDevices instead.
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 deprecation warning explicitly tells the agent to use listDevices instead, which is clear guidance for when not to use this tool. However, it does not clarify when it would be appropriate to use this tool over alternatives, nor does it explain the trade-offs between this and listDevices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It only states the action without disclosing whether the operation is read-only, requires specific permissions, has rate limits, or any side effects. The lack of any behavioral context significantly reduces transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one sentence, but this brevity sacrifices completeness. While there is no wasted text, the lack of additional context makes it minimally acceptable.
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 no annotations, the description is insufficiently complete. It does not explain return values, prerequisites (e.g., whether the gateway must be managed by the site), or how this tool fits among the many sibling getters.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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, already describing all three parameters including defaults and patterns. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: retrieving the SIM card used by a gateway. It uses a specific verb ('Get') and resource ('SIM card used by a gateway'), which aligns well with the tool name and distinguishes it from sibling tools like getGatewayDetail that may return broader gateway information.
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 getGatewayDetail or other getters. There is no mention of prerequisites, use cases, 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 bears full responsibility for behavioral disclosure. It only states the high-level purpose, omitting details such as whether the gateway must be online, what 'health details' include, error handling, or performance implications. This is insufficient for a tool that likely requires specific permissions and depends on network state.
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 at one sentence (8 words), but this brevity sacrifices informative content. While it contains no fluff, it does not earn its place because it omits necessary context. A rating of 3 reflects that it is neither verbose nor sufficiently detailed.
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 the tool returns (e.g., 'health details' could include port status, speed, errors, etc.). It also does not mention any side effects or that it is a read-only operation. For a tool with moderate complexity (nested objects), 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?
The input schema has 100% coverage, so the schema already documents each parameter well (e.g., siteId, gatewayMac with examples, customHeaders). The description adds no additional meaning beyond what the schema provides, meeting the baseline 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 action ('Get') and the resource ('WAN port health details for a gateway'). It is a specific verb+resource combination. However, it does not distinguish from similar sibling tools like getGatewayWanStatus, which may also return health information, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 does not mention any prerequisites or when not to use it. Usage is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read operation but does not disclose any behavioral traits (e.g., authentication, rate limits, pagination, or side effects). The description is too minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence). While concise, it lacks structure and omits important details, 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 that there is no output schema and the tool returns complex info (nested objects), the description fails to explain what 'easy managed switch info' includes or how the response is structured. It 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 coverage is 100%, with each parameter having a description. The tool description adds no new parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get easy managed switch info' clearly identifies the resource (easy managed switch) and the action (get info). It distinguishes from siblings that target specific details (e.g., getSitesSwitchesEsGeneralConfig, getSwitchDetail), though 'info' is somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. Siblings like getSitesSwitchesEsGeneralConfig or getSwitchDetail exist, but no usage context or exclusions are given.
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 provided, and the description offers no behavioral details (e.g., read-only, rate limits, required permissions). It merely restates the tool name's purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose. It is concise but could benefit from a brief note on typical usage without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description fails to indicate return format, pagination, or limitations. Users are left uncertain about the data structure.
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%, but the description adds no parameter-level information. The required parameter stackId lacks description in both schema and description, and siteId's description is only in 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 'all port information for a switch stack.' It distinguishes from siblings like getGatewayPorts and getSwitchStackDetail by specifying port information for a stack.
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., getSwitchDetail for individual switch ports or listSitesStacks for stack listing). No context about 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 are provided, placing full burden on the description. It only states the tool fetches information but fails to disclose idempotency, required permissions, error scenarios, or return format (e.g., single object vs. array). Essential behavioral traits 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—a single sentence that directly states the tool's purpose. It is well front-loaded and contains no extraneous information. Every word is earned.
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 description does not explain what 'detailed information' entails (e.g., JSON structure, fields). The tool involves a nested object parameter (customHeaders), but no behavioral context is provided. The description is incomplete for a tool of this complexity.
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?
With 67% schema coverage (siteId and customHeaders described), the description adds no parameter context. It omits explaining the required stackId (e.g., its origin from listSitesStacks) and does not clarify the role of optional parameters beyond the schema. No value added over the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('detailed information for a specific switch stack'), clearly distinguishing it from sibling tools like getSwitchDetail (for switches) and listSitesStacks (lists all stacks). However, 'detailed information' is somewhat vague; mentioning specific attributes like configuration or status would improve clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as getStackNetworkList or getStackPorts. The description does not mention prerequisites, siteId handling, or the appropriate 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?
With no annotations, the description carries full burden. It only says 'get incremental results' without detailing behavior such as whether results are cumulative, paginated, or what data is returned. No side effects or safety info is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single brief sentence, which is concise but lacks structure. It could be expanded to cover key points without becoming overly long. Not wasteful but underinformative.
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 sibling tools, more context is needed. The description does not explain what 'incremental results' means, how to interpret them, or how they relate to other cable test tools. Incomplete 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 description coverage is 100%, so the schema itself documents all parameters well. The tool description adds no additional meaning beyond the schema. Meets baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'cable test incremental results for a switch'. It differentiates from siblings like 'getCableTestFullResults' and 'getCableTestLogs' by specifying 'incremental', but could be more explicit about scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not mention when to use this tool over alternatives (e.g., full results or logs), nor any prerequisites or context. This leaves the agent without guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It does not mention whether the tool is read-only, requires authentication, or how pagination works. The schema implies pagination, but the description does not confirm or elaborate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded with the verb 'Get'. No extraneous words. Efficiently communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is too brief. It fails to explain the return format, pagination behavior, or what constitutes a firmware upgrade plan, leaving gaps for the 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 67% (page and pageSize described, customHeaders missing). The description does not add any parameter-specific meaning beyond the schema. Baseline set at 3 due to moderate coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves a list of firmware upgrade plans for devices managed by the controller. However, it does not distinguish from sibling tools like getFirmwareInfo or listUpgradeFirmwares, which may have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 over alternatives, such as getFirmwareInfo or listUpgradeFirmwares. There is no mention of prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It describes the tool as retrieving a list, which implies a read operation, but does not disclose behavioral details such as pagination behavior (despite params for page/pageSize), response structure, or whether it is read-only. Basic transparency is present.
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, concise and front-loaded with the main purpose. Every sentence adds value, though it could be slightly more efficient by combining the second sentence with the first.
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 is incomplete. It does not specify what fields the response contains, how pagination is handled, or any potential cost (e.g., rate limits). For a list tool, more detail is needed for complete contextual understanding.
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 described in schema). The description does not mention any parameters or provide additional meaning beyond what the schema already offers. 'customHeaders' is undocumented in both schema and description, leaving a 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 it retrieves the auto-check upgrade plan list showing scheduled firmware upgrade checks. It uses a specific verb ('Get') and resource ('auto-check upgrade plan list'). It is distinct from sibling tools like getFirmwareUpgradePlan, though not explicitly differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for auditing schedules but provides no explicit guidance on when to use this tool versus alternatives (e.g., getFirmwareUpgradePlan, getUpgradeLogs). No when-not or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits but fails to do so. It does not state whether the operation is read-only, how performance is affected, or if any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. While concise, it is slightly under-specified, but the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters and no output schema, yet the description provides no information about return values, response format, or expected behavior. Given the complexity of sibling tools, 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 coverage is 100% with detailed descriptions for each parameter (e.g., apMac format, siteId default, customHeaders usage). The tool description adds no new meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get available channels for an AP,' specifying a concrete verb and resource. However, it lacks detail on what constitutes 'available channels' and does not differentiate from closely related sibling tools like getApRadios or getSitesApsChannelLimit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives is provided. The parameter descriptions include hints (e.g., using listDevices to find apMac), but no explicit context for selection among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only says 'Get', implying read-only, but does not disclose error behavior, prerequisites, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, front-loaded with the action. Could benefit from slightly more detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no annotations. The description fails to explain what P2P bridge config entails, what the response looks like, or any prerequisites beyond parameter hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 documented parameters. The description adds no extra parameter meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get P2P bridge config for an AP,' specifying a distinct config type among many sibling AP config tools. However, it does not elaborate on the scope or relation to siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., getApGeneralConfig). The description lacks any usage context or exclusionary hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description only says 'Get', implying a read operation, but provides no additional behavioral details such as authorization requirements, side effects, or rate limits. With no annotations, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words. While very short, it is appropriately concise and front-loaded with the action and subject.
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 presence of three parameters (including customHeaders), no output schema, and many sibling tools, the description is insufficiently complete. It does not explain what the channel limit config consists of or how to interpret 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 coverage is 100%, so parameters are already described in the schema. The description adds no extra meaning beyond what is in the schema, meeting the baseline but not exceeding 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 specifies a clear verb ('Get') and resource ('channel limit config for an AP'), making the basic purpose understandable. However, it does not differentiate from many similar sibling tools like getSitesApsAvailableChannel or getSitesApsLoadBalance.
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 indicate prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits beyond the implicit read-only nature. It fails to mention any potential side effects, authorization requirements, or rate limits, leaving the agent without crucial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and concise. However, it could be expanded slightly to include more context without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should at least hint at the structure of the returned IP settings (e.g., IP address, subnet mask, gateway). It does not, making it incomplete for the agent to understand the tool's full behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the parameter descriptions in the schema already provide, such as the format of apMac or the default behavior of siteId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves IP settings for an access point, using a specific verb and resource. However, it does not explicitly distinguish it from sibling tools like getApIpv6Config or getApGeneralConfig, which might overlap.
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. The description lacks context about prerequisites, typical use cases, or conditions under which other tools should be 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?
No annotations are present, and the description only indicates a read operation ('Get') without explicitly stating it is non-destructive, required permissions, or potential side effects. The description fails to compensate for the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is front-loaded but lacks detail, which slightly reduces effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and minimal description, the tool lacks context about return values, prerequisites (e.g., does the AP need to be online?), or expected response format. A more complete description would improve agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described. The description adds no extra 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.
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 (trunk setting for an AP), distinguishing it from other get* AP tools. However, 'trunk setting' is not elaborated, which may cause ambiguity for agents unfamiliar with network terminology.
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 the many sibling tools (e.g., getApDetail, getSitesApsChannelLimit). No when-not-to-use 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?
With no annotations, the description should disclose behavioral traits. It fails to mention that this is a read-only operation (no destructive effect), that results are paginated, or other side effects. The minimal description leaves the agent guessing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is efficient. However, it could be slightly more informative without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, pagination, and no output schema, the description is too brief. It does not explain what the whitelist represents, the return format, or behavior when siteId is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 extra meaning beyond the schema; it does not explain the purpose of the whitelist or how the parameters relate.
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'), making it distinct from sibling tools like getAllDeviceBySite or getDevice. However, it does not specify that the result is a list or note pagination.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like getAllDeviceBySite. The description lacks context for choosing this tool over similar getters.
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 the tool is read-only, potential side effects (none expected), or error conditions like invalid gateway MAC. This leaves the agent without critical 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?
The description is a single sentence with no wasted words. It is appropriately sized for a simple retrieval operation, though it could benefit from slightly more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks crucial context: no explanation of what 'general config' includes, no mention of output format (since there is no output schema), and no clarification on how this tool compares to similar ones like getGatewayDetail. This leaves significant gaps for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented. The description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves gateway general config, which is a specific verb-resource combination. However, it does not differentiate from sibling tools like getGatewayDetail or getApGeneralConfig, which also retrieve 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 over alternatives, nor are there any exclusions or prerequisites mentioned. The description merely states the action without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavior. It states 'Get' which implies a safe, read-only operation, but it does not confirm that no state is modified, nor does it mention any required permissions, rate limits, or side effects. The lack of behavioral details is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise with one clear sentence that front-loads the verb and resource. However, it omits any context or examples, which would improve usability without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema, so the description should at least hint at what the PIN setting looks like (e.g., format, data type). It also does not explain what 'PIN setting' means, leaving the agent to infer. Given the tool's simplicity, more context is needed for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, meaning the schema already explains each parameter in detail. The description adds no additional semantic value beyond the schema's descriptions. Baseline score of 3 is appropriate here.
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 the PIN setting for a gateway, specifically an LTE model. It uses a specific verb ('Get') and resource ('PIN setting for a gateway'), distinguishing it from sibling tools like getGatewayDetail or getGatewayLanStatus. However, it could be more explicit about the data being read-only.
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 (e.g., gateway must be LTE model) or when not to use it. The single sentence lacks any contextual instructions for the agent.
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 behavioral burden but only states 'List ports on an AP.' It does not disclose whether the operation is read-only, what permissions are needed, or any side effects. This is insufficient for an agent to understand the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. It efficiently conveys the tool's function without extraneous text, though it omits details that could aid selection.
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 three parameters and no output schema, the description lacks details about the returned data (e.g., port status, speed) and does not help an agent decide whether this tool is appropriate compared to many sibling tools. The minimal description leaves gaps for effective decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters adequately. The description adds no further semantic nuance beyond what is in the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'ports on an AP', making the tool's function obvious. It differentiates from sibling tools like getGatewayPorts and getStackPorts by specifically targeting AP 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?
No guidance on when to use this tool versus alternatives like listSitesCableTestSwitchesPorts or getApDetail. There are no prerequisites or usage scenarios mentioned beyond the parameter hints in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Only states 'Get' implying read-only, but fails to disclose error behavior (e.g., AP not found), rate limits, or required permissions. Lacks details on what 'IPv6 configuration' entails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise, but under-specified. Could be improved by adding usage context without significant length increase.
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 description should explain return value or clarify scope. Lacks information on site dependency, return format, or relationship with other AP config getters. Incomplete for a tool with 3 parameters and nested objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully documented in schema. Description adds no additional meaning beyond schema fields. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'IPv6 configuration' for a specific access point. Distinguishes from siblings like getApGeneralConfig, getApLldpConfig, etc., which target different configuration types.
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. Does not mention prerequisites (e.g., AP must be adopted), context for IPv6 vs IPv4, or when to prefer sibling tools like getApGeneralConfig.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must cover behavioral traits. It only states the action without disclosing read-only nature, authentication requirements, side effects, or error conditions. The brevity leaves the agent without essential safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise, but it under-specifies the tool's purpose and behavior. Could add more context without excessive length (e.g., mention OFDMA is for 802.11ax). Not concise in a helpful way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no description of return values or what 'OFDMA configuration' entails. Given the complexity of 3 parameters including a nested object, the description is insufficient for an agent to understand the tool's full behavior and 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 description coverage is 100% with adequate param descriptions (e.g., apMac regex example, siteId fallback). The tool description adds no extra meaning beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get OFDMA configuration for an AP' uses a specific verb and resource (OFDMA configuration for an AP), which clearly distinguishes it from sibling tools that target other AP settings like radios, VLAN, or 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 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 other AP configuration tools (e.g., getApDetail, getApRadios). The parameter descriptions hint at prerequisites (use listDevices for MAC, listSites for siteId) but no explicit when-to-use or when-not-to-use 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?
With no annotations, the description carries full burden, but it only says 'Get power saving config for an AP.' It does not state that the operation is read-only, whether errors occur for unsupported APs, or any prerequisites. The name implies a read, but formal transparency is lacking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. It earns its place but could be expanded to include context about the return format or usage notes without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite only 3 parameters, the description omits details about the return value (no output schema) and possible error conditions. The tool would benefit from explaining what the power saving config contains or how to interpret responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The tool description adds no extra meaning beyond the schema; it merely restates the action. 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 'Get power saving config for an AP.' uses a specific verb and resource, clearly distinguishing it from sibling tools like getApGeneralConfig or getApRadios. It directly states what the tool retrieves.
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 (e.g., other AP config tools). The only implicit hint is in the input schema's apMac description referencing listDevices, but that does not address 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic function, without any mention of side effects, permissions, rate limits, or return behavior. The agent has no information about the safety or side effects of this call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, concise and front-loaded. However, it is so brief that it sacrifices necessary detail; still, it avoids unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one undocumented parameter and no output schema. The description does not hint at the return format (e.g., whether it returns a number, object, or list). Given the complexity of the sibling tools and the lack of schema coverage, the description is insufficient for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (customHeaders) with no description in the schema (0% coverage) and the tool description does not explain its purpose, format, or usage. The description adds zero value beyond the schema for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'the number of critical firmware upgrades', and the scope 'across managed devices'. It is specific and distinguishes from sibling tools like getFirmwareUpgradePlan which provides more detailed plans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for obtaining a count of critical upgrades, but does not specify when to prefer it over getFirmwareUpgradePlan or getUpgradeOverviewTryBeta.
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 behavior. It does not mention that the operation is read-only, whether authentication is required, or how errors (e.g., missing site) are handled. This leaves significant behavioral ambiguity for the agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and its key output metrics. No extraneous words, making it concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify the return format and structure. It lists metrics but doesn't indicate whether they are returned as individual fields or aggregated. Missing details on error handling, pagination, or performance implications for the 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?
Both parameters (siteId, customHeaders) are fully described in the input schema with 100% coverage. The description adds no further 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.
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 a switch summary for a site dashboard and lists specific metrics (switch count, ports, PoE budget, bandwidth). This distinguishes it from other dashboard tools like getDashboardPoEUsage, though it could more explicitly contrast with siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for getting a site's switch summary but offers no guidance on when to choose this tool over alternatives like getDashboardMostActiveSwitches or getDashboardOverview. No exclusion criteria or preconditions 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 bear all behavioral disclosure. The description only says 'Get', implying a read operation, but does not disclose authentication needs, rate limits, error behavior, or what happens on failure. This is insufficient for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it very concise. It is front-loaded with the key information. However, it could be slightly expanded to include more context without becoming overly long.
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 no annotations, the description is too brief. It does not explain what 'general config' includes, how to interpret the response, or any prerequisites (e.g., switch must be online). It is incomplete for an AI agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented in the schema. The description adds no additional meaning beyond the schema, such as clarifying what 'general config' includes or expected return format. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get easy managed switch general config' clearly states the verb (Get) and the resource (easy managed switch general config). It is specific to easy managed switches, but does not explicitly differentiate from sibling tool 'getSwitchGeneralConfig' which likely targets regular switches.
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 usage guidelines are provided. The tool is implied for easy managed switches based on naming, but there is no when-not or alternative guidance. Sibling tools exist for APs, gateways, and regular switches, but no contextual advice is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description is minimal and does not disclose behavioral traits such as read-only nature, authentication needs, or pagination behavior. The agent must infer safety from 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?
Single-sentence description is concise with no waste. However, it could be more structured (e.g., front-loading key constraints) but remains 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?
Given the lack of output schema and 4 parameters (with pagination), the description is too minimalist. It does not explain the return format, what a 'stack' is, or how pagination works beyond schema hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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. The description adds no additional meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (list) and resource (switch stacks in a site). It distinguishes from sibling tools like getSwitchStackDetail which gets details of a single stack.
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., getSwitchStackDetail, getStackNetworkList). No context on prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It only states the core function without mentioning read-only nature, authorization requirements, default site behavior, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the purpose. It efficiently uses words but could include more detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full schema coverage, the description is minimally adequate. However, it lacks context about the return format, error handling, or what constitutes a device tag, and fails to leverage the absence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description adds no additional meaning beyond what is in the schema, which is adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'device tags', and the scope 'in a site'. It is specific and distinguishes this tool from sibling tools that deal with devices, clients, or other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The sibling list is large but no differentiation is offered.
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 is minimal and does not disclose behavioral traits like authentication requirements, rate limits, or side effects. It only states the basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loads the action and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing details about output format, pagination, error handling, and relationship to other cable test tools. The description is too minimal for a tool with no output schema and no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra meaning beyond what's in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'ports', and the context 'for cable test on a switch'. It distinguishes from siblings like getCableTestFullResults which retrieve results, not 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?
No guidance on when to use this tool vs alternatives such as listSitesCableTestSwitchesIncrementResults or getCableTestLogs. No prerequisites or exclusions are mentioned.
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 the burden. It indicates a read operation with no side effects, but lacks details on prerequisites (e.g., AP must be adopted, needed permissions). Adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences; the first is concise and informative. The second sentence ('LLDP allows...') is generic and may not be necessary for an AI agent, slightly reducing efficiency.
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 simple parameters, the description covers the basic purpose and return. But it omits potential error conditions or state dependencies (e.g., AP offline). Moderately 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 covers 100% of parameters with descriptions, including format and defaults. The tool description adds no extra semantic value beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Get LLDP configuration for an access point' and specifies the return values ('enabled state and advertised TLVs'), clearly distinguishing it from sibling tools like getApGeneralConfig or getApSnmpConfig.
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 getApGeneralConfig or getApSnmpConfig. The description does not provide context for when LLDP configuration is relevant or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only names the return fields, omitting details such as whether the data is real-time or cached, required permissions, or any side effects. While the tool is likely read-only, the description does not explicitly state this.
Agents need to know what a tool does to the world before calling it. Descriptions 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 20 words that immediately states the tool's purpose and lists the fields. There is no redundant information, and the structure is perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain the response structure. It lists the fields but does not clarify how they are organized (e.g., whether channel utilization is a nested object). The description is adequate for basic understanding but lacks detail on the output format, which is needed given the lack of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both siteId and customHeaders have descriptions in the schema). The tool description adds no additional parameter information beyond what is already in the schema, so it does not enhance understanding beyond the structured input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 the exact fields returned: total APs, connected AP count, wireless client count, channel utilization per band, and SSID count. It uses a specific verb ('Get') and resource ('WiFi summary for a site dashboard'), and the listed fields distinguish it from sibling dashboard summaries like 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, context, or exclusion criteria, leaving the agent to infer appropriateness solely from the tool name and field list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature, scope (all devices vs. specific), or pagination behavior beyond schema defaults.
Agents need to know what a tool does to the world before 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, 14 words, front-loaded verb, no redundant information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers basic purpose but misses scope (all devices or filtered?), output format, and prerequisites. Adequate for a simple tool but insufficient given missing annotations and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (page and pageSize documented, customHeaders undocumented). The description adds no additional meaning for any parameter, so it meets baseline but does not compensate for the undocumented 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?
The description explicitly states it retrieves firmware upgrade logs, which is a specific verb and resource. It distinguishes from upgrade-related siblings like getFirmwareInfo or getFirmwareUpgradePlan by focusing on logs of past operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. With many upgrade-related siblings, the description lacks context on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It does not mention side effects, permissions, rate limits, or whether the operation is read-only, leaving uncertainty.
Agents need to know what a tool does to the world before 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 first sentence immediately specifies the action and resource, making it easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description adequately explains the return content (history, per-port results, length estimates, fault detection). It covers the core need but lacks details on pagination or sorting.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional parameter-level context, meeting the baseline expectation.
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 cable test logs for a switch, including specific details like per-port results and fault detection. It differentiates from sibling 'getCableTestFullResults' by focusing on 'logs' (history) versus full results, though not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case ('diagnosing physical layer connectivity issues') but lacks explicit when-to-use or when-not-to-use guidance compared to sibling tools. No alternatives 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 provided; description only states basic function. Lacks info on read-only nature, pagination, rate limits, or historical data range. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words, directly states what the tool does. Efficient 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?
Tool has no output schema and no annotations; description does not summarize return format, data range, or usage constraints. Incomplete for agents needing to understand output or limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with detailed descriptions (siteId and customHeaders). Description adds no extra meaning beyond the schema. Baseline 3 maintained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 retrieves time-series traffic activity data for a site, with upload/download trends. Distinguishes from siblings like getDashboardOverview by specifying traffic focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for traffic trends but no explicit guidance on when to use versus alternatives or when not to use. No exclusion criteria 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 must fully convey behavioral traits. It states the tool returns firmware information, implying read-only behavior, but does not explicitly confirm no side effects, authorization needs, or potential errors. For a tool with zero annotation coverage, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no waste: the first sentence states purpose and output, the second gives a concrete prerequisite. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the tool's purpose and key parameters but lacks details on the return format (no output schema) and possible error conditions. Given the simplicity of the tool, this is minimally adequate.
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%, and the description adds value beyond the schema by explaining the purpose of deviceMac and siteId, noting how to obtain valid values (listDevices, listSites), and describing the default behavior for siteId. The customHeaders parameter is also well 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 the tool retrieves the latest available firmware information for a device and lists specific return fields (current version, latest available, upgrade availability). However, it does not explicitly distinguish itself from many firmware-related sibling tools (e.g., getFirmwareUpgradePlan, 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 provides a prerequisite ('Use listDevices to get deviceMac values') but offers no guidance on when to use this tool versus alternatives like getFirmwareUpgradePlan or listUpgradeFirmwares. Usage context is only implied.
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 describes the returned data but does not disclose side effects, authorization needs, rate limits, or whether the operation is read-only. For a gateway status tool, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the primary purpose and a clear prerequisite. No unnecessary words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a good overview of the tool's output and a prerequisite step. Without an output schema, it explains the returned attributes adequately, though it could be more explicit about the output structure (e.g., list of 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 documentation covers 100% of parameters, so the description adds minimal value beyond reiterating the prerequisite. The baseline of 3 is appropriate as the description does not highlight additional constraints or format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves LAN port status for a specific gateway and lists the specific attributes (link state, speed, duplex, connected device, VLAN). However, it does not explicitly distinguish itself from sibling tools like getGatewayPorts or getGatewayWanStatus.
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?
It provides a prerequisite instruction (use listDevices to get gatewayMac) but lacks guidance on when to use this tool versus alternatives. No comparison to related tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must fully disclose behavioral traits. It describes return fields but omits permissions, rate limits, side effects, or data freshness. For a read operation, more context on authorization and data stability 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?
Two sentences with no fluff: first states purpose and pagination, second lists return fields. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 6 parameters, no output schema, and no annotations. Description covers purpose, fields returned, and pagination (implied), but could explicitly explain pagination behavior (e.g., total results, navigation). Still, it is sufficiently complete for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a clear verb-resource structure ('Get per-client connection history') and specifies pagination. It distinguishes from sibling tools like 'getClient' (current info) and 'listClientsPastConnections' (likely similar but description adds detail on fields returned).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as 'listClientsPastConnections' or 'getClientDetail'. The description lacks context for appropriate selection among similar history/activity 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?
Describes pagination and filtering, but lacks details on pagination behavior, rate limits, or data range 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?
Two sentences, no fluff, front-loaded with action verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema provided, and description does not hint at return fields or structure, leaving gap for a tool with 9 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 covers 100% of parameters with descriptions; description only adds context about time range and search, not enough to raise above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves a paginated list of historical known clients with optional filters. Distinguishes from current clients tools but not from similar 'getGridClientHistory' sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies historical data retrieval but does not explicitly state when to use over siblings or provide 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 behavioral traits such as whether the tool is read-only, requires authentication, or has side effects. For a read operation, it is safe, but the description fails to explicitly state this.
Agents need to know what a tool does to the world before 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 clearly states the tool's purpose, the second provides a critical usage hint. No unnecessary words, front-loaded with essential 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's simplicity and full schema coverage, the description is adequate but lacks details about the return format (e.g., it returns a configuration object). For a tool with no output schema and no annotations, a bit more context would be helpful.
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%, and the description adds value by advising to use listDevices to obtain switchMac values. This helps agents understand how to populate the required parameter beyond the schema's pattern constraint.
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 general configuration for a switch, listing specific categories like LED settings, LLDP, flow control. This differentiates from sibling tools like getApGeneralConfig (for APs) and getSwitchDetail (which likely returns more detailed info), though not explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides one usage hint: 'Use listDevices to get switchMac values.' This helps with the required parameter, but there is no guidance on when to use this tool vs alternatives like getSitesSwitchesEsGeneralConfig, or prerequisites like siteId (though optional).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only restates the timestamp format already in the schema and does not disclose any behavioral traits (e.g., rate limits, auth requirements, or side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences with minimal redundancy. The mention of Unix timestamps is partially redundant with the schema but not overly wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately hints at return format (breakdown by category) but lacks details on pagination, error handling, or additional context like siteId behavior beyond the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter described. The description adds no new semantic meaning beyond what is in 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 tool retrieves traffic distribution by protocol and application type over a time range, with specific categories like video and gaming. It distinguishes from siblings such as getClientsDistribution.
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 bandwidth consumption analysis but provides no explicit guidance on when to use this tool versus alternatives like getClientsDistribution, nor when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. However, it only states the purpose and does not mention that the operation is read-only, requires no special permissions, or any other behavioral aspects. The lack of transparency is significant 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 with only 10 words. Every word earns its place, and there is no redundant or extraneous 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 no output schema and a simple read operation, the description is minimally viable but lacks context about return format, error handling, or any side effects. It could be more helpful by stating that the QoS configuration is returned, but 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 description coverage is 100%—all parameters have descriptions in the schema. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get QoS configuration for a specific access point' clearly specifies the verb 'Get', the resource 'QoS configuration', and the scope 'for a specific access point'. It effectively distinguishes from sibling tools like getApGeneralConfig or getApIpv6Config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., other getAp* tools). The usage is implied by the tool name and description, but there is no mention of when not to use it or alternative tools for similar tasks.
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 it retrieves top devices by CPU usage, but does not mention whether the operation is read-only, if it requires special permissions, or if there are any side effects. The safety profile is unclear, and missing details like pagination or response format reduce transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the primary action ('Get the top devices by CPU usage for a site') and adds a brief purpose. No extraneous words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 optional parameters and no output schema. The description provides the key functionality but does not explain the return format (e.g., is it a list, sorted, limited count?). For a simple read tool, it is mostly complete but lacks output details that could affect agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already explains both parameters. The tool description adds no additional meaning or context for the parameters (e.g., what constitutes 'top' or how siteId default works). 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.
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 'top devices by CPU usage', and the scope 'for a site'. It distinguishes from sibling tools like getDashboardTopMemoryUsage by focusing specifically on CPU usage, making it easy for an agent to select this tool over alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions it is 'useful for identifying overloaded devices', which implies a use case. However, it does not explicitly state when not to use this tool or provide direct comparisons to sibling tools (e.g., getDashboardTopMemoryUsage). The guidance is adequate but lacks exclusions or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the tool returns a time-series but does not disclose behavioral traits such as read-only nature, authentication requirements, rate limits, or potential side effects. The description is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, no unnecessary words. It front-loads the purpose and then specifies the requirement. 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 no output schema and the tool's complexity (time-series data), the description is somewhat incomplete. It does not detail the format of the returned time-series (e.g., intervals, data points, units). However, parameters are well-documented in the schema, and the tool's purpose is clear. A 3 reflects adequate but not thorough 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 little beyond the schema: it reiterates that start and end are Unix epoch seconds (already in schema) and does not elaborate on siteId or customHeaders beyond what is in the schema. Baseline 3 is appropriate as the description provides minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a historical client count trend over a time range, specifying it returns a time-series of client counts. This is a specific verb and resource, and it distinguishes from sibling tools like getClient or listClientsPastConnections by focusing on the trend over a range.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required parameters (start and end as Unix epoch seconds) but does not provide explicit guidance on when to use this tool versus alternatives. It does not list exclusions or conditions for use, leaving the agent to infer from 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 bears full responsibility. It indicates a read operation but lacks details on pagination, rate limits, authentication needs, or any side effects. The description does not go beyond the minimal verb+object.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-organized sentences with a clear action, output description, and a prerequisite tip. No redundant or extraneous 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?
For a tool with 5 parameters and no output schema, the description only vaguely explains the return value ('VLAN interface assignments'). It lacks details on format, structure, or any example. While the schema covers parameter domains, the description should provide more context on the output to be minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptive texts and constraints (e.g., page, pageSize, stackId). The description adds no additional parameter semantics beyond what the schema already provides, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 VLAN network list for a switch stack' and specifies the output: 'Returns VLAN interface assignments across all stack members.' This distinguishes it from sibling tools like getStackPorts or getSwitchStackDetail.
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 instruction: 'Use getSwitchStackDetail to get the stackId,' but does not explicitly state when to use this tool versus alternatives or any exclusion criteria. The guideline is helpful but limited.
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 like side effects, authorization requirements, or rate limits. It only describes the output content without addressing potential impacts 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?
Two sentences: first provides a dense, informative overview of the output; second offers a practical prerequisite tip. No superfluous words. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description adequately enumerates key return fields. However, it omits structural details (e.g., whether the response is an object or array) and error scenarios. Slightly incomplete for a tool with 3 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%, and the description adds minimal value beyond the schema descriptions. The note about using listDevices for apMac is helpful but not parameter-specific semantics. 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 specifies the exact verb 'Get', the resource 'radio status', and lists the specific data fields (band config, channel, TX power, channel utilization, client count). It also distinguishes from sibling tools by focusing on radio status rather than general AP detail or config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a prerequisite ('Use listDevices to get the apMac') but does not provide guidance on when to use this tool versus alternatives such as getApDetail or getRadiosConfig. No explicit when-not or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It implies a non-destructive read operation but does not explicitly state read-only status, auth requirements, or potential side effects. The listed return fields provide some 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 very concise: two sentences that front-load the purpose and provide immediate value. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool, the description adequately explains what the tool returns and its purpose. No output schema is present, but the description compensates by listing return fields. Could be improved by noting required permissions or rate 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%, and the description does not add any parameter-level meaning beyond what the schema already provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb ('Get') and the resource ('SNMP configuration for an access point'), and lists what is returned. However, it does not explicitly distinguish from sibling tools like getApDetail or getApGeneralConfig, which limits differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a use case ('auditing SNMP-based monitoring configurations') but lacks explicit guidance on when to use this tool versus alternatives, and does not mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the tool is read-only and returns specific data. It lacks disclosure of error handling, authentication requirements, or other 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 concise sentences that front-load the purpose and add a use case. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return values (management VLAN and per-SSID settings). Lacks error case details but is sufficient for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all parameters. The description adds no new information beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves VLAN configuration for an access point, specifying the resource (VLAN config) and the scope (per-SSID). Distinguishes well from 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions a use case (verifying network segmentation) but does not explicitly state when to use this tool over alternatives like getApDetail or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as side effects, required permissions, or rate limits. The read-only nature is implied but not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The main purpose is front-loaded, and every word adds value without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given moderate complexity with nested objects and no output schema, the description adequately explains the tool's output conceptually. However, it could benefit from mentioning the return format (e.g., 'returns an object with bands as keys').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds no additional meaning beyond what the input schema already provides for siteId and customHeaders. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'client count distribution', specifying grouping by connection type and band. It effectively distinguishes from sibling tools that focus on devices, APs, or 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 provides a use case ('useful for understanding network composition at a glance') but does not offer explicit guidance on when to use this tool versus alternatives like listClients or getTrafficDistribution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral transparency. However, it adds minimal behavioral context: it does not state that the tool is read-only, what happens when a site has no switches, or any rate limits. The description essentially repeats the tool name's implication without enriching the agent's understanding of 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?
A single sentence of 10 words that captures the tool's core purpose without redundancy. Every word earns its place. The structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 two parameters and no output schema, the description is largely complete: it states what is returned (most active switches) and how it's sorted (by traffic volume). The parameter descriptions in the schema handle parameter semantics. Additional details about return format (e.g., list of switch IDs/names with traffic metrics) are not critical but could slightly improve completeness for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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%: both parameters have descriptions. The tool description does not add any information beyond what the schema already provides for parameters. Baseline is 3, and no extra value is contributed by the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the most active switches in a site, sorted by traffic volume' clearly specifies a verb ('Get'), resource ('most active switches'), scope ('in a site'), and ordering ('sorted by traffic volume'). It distinguishes itself from siblings like getSitesSwitchesEs (which lists all switches) and getDashboardMostActiveEaps (which targets EAPs, not switches), effectively conveying its unique purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied ('get the most active switches'), but there is no explicit guidance on when to use this tool over alternatives, such as when a full list of switches is needed or when switch details are required. The schema description for siteId provides helpful context about default site and discovery via listSites, but this pertains to parameter usage rather than tool-level guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It indicates a read-only operation without side effects, but does not disclose authentication requirements, potential rate limits, or behavior when no PoE data exists. It is adequate but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 17 words that efficiently conveys the tool's purpose and output. It is front-loaded with the action and resource, leaving 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?
Given the simplicity of the tool (2 parameters, no output schema), the description provides sufficient context about the data returned. It explains the granularity (per switch) but could mention aggregation or time scope. Still, it is more complete than minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds the output context (per switch) but does not enhance parameter understanding beyond the schema. Baseline 3 applies as schema already documents parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves PoE usage statistics for a site, specifically showing power consumption per switch. This is distinct from sibling dashboard tools like getDashboardOverview or getDashboardMostActiveSwitches, as it focuses on PoE metrics.
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 other dashboard tools or device-level PoE queries. 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description implies a read-only operation. It does not disclose potential edge cases (e.g., missing config), permissions, or side effects, but for a simple get config, it is minimally adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, with zero superfluous content. Highly concise while still 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 simple read nature and 100% schema coverage, the description is nearly complete. It lacks output format details but that is compensated by clarity of purpose and schema. Slightly better than minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full parameter descriptions (100% coverage), so the tool description adds no extra meaning. Baseline of 3 is appropriate as the schema already clarifies 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 uses specific verb 'Get' and resource 'load balance config for an AP', clearly distinguishing it from sibling tools like getApGeneralConfig or getApQosConfig. It precisely states the action and target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 getApGeneralConfig or getApRadios. The description does not mention context or exclusions, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description indicates a read operation but does not disclose any behavioral details beyond that. 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 with no unnecessary content. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple and parameters are fully documented, the description could briefly mention the return value (e.g., the authentication setting details) 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 description coverage is 100%, so parameters are well-documented. Description adds no extra meaning 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 verb 'Get' and the specific resource '802.1X switch port authentication setting', distinguishing it from sibling getters like getSwitchGeneralConfig.
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., general config getters). No mention of prerequisites or context for using the setting.
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; description lacks disclosure of side effects, permissions, or return format. Only mentions fuzzy search and filtering, missing key 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 sentences, front-loaded with purpose and pagination, then filtering details. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what 'statistics' means (e.g., counts, aggregations). Missing response semantics and does not cover all parameters like customHeaders.
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?
Adds meaningful context for most parameters (fuzzy search fields, filtering by tag and series type), compensating for low schema coverage. However, customHeaders is unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it queries statistics for global adopted devices with pagination and filtering, distinguishing it from sibling tools like listDevices and searchDevices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for aggregated statistics rather than detailed device info, but no explicit when/when-not guidance relative to similar 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?
The description indicates a read-only operation returning historical data, but lacks details on permissions, rate limits, or side effects. With no annotations, the description carries the burden and is moderately 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: first clarifies purpose, second lists features. Every word adds value, and the structure is efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key features and parameters, but lacks details about the return format or pagination behavior. Given no output schema, this is a noticeable gap for a tool with 9 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 high (89%), so the schema already documents most parameters. The description groups features (pagination, filtering, sorting) adding some value, but does not provide deep parameter semantics beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets historical connection data for clients, using specific verbs and resources. It distinguishes itself from sibling tools like listClients (current clients) and getClientDetail (single client) by focusing on past connections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for historical data retrieval but does not explicitly compare with alternatives or state when not to use it. An agent would infer usage from context, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states what data is returned but does not mention whether the operation is read-only, requires special permissions, or has any side effects, leaving a significant gap for a tool with no safety annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loads the verb and resource, includes a sibling comparison, and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description offers a reasonable overview of return fields (cable status, length, fault location) and implies an array structure per port, which is sufficient for an agent to understand the nature of the output, though full completeness would require more structural detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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, achieving 100% schema description coverage. The description does not add extra meaning or usage details beyond what the schema already provides, meeting the baseline but not exceeding 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 it retrieves full cable test results for all ports on a switch, and distinguishes itself from the sibling tool getCableTestLogs by noting it provides more detailed data including cable status, length, and fault location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (for detailed per-port diagnostics) and compares it to getCableTestLogs as a less detailed alternative, but does not explicitly state when not to use it or mention other alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 filters the site client list in-process to emulate a per-client lookup, implying potential inefficiency. However, it does not mention authentication requirements, rate limits, or behavior when clientId is not found. The deprecation notice is a positive 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?
Two sentences: first covers deprecation and alternatives, second explains the mechanism and purpose. No wasted words, but could be more structured with bullet points. Efficient for the content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and moderate parameter count, the description explains the basic behavior and usage context (deprecation, alternative methods). However, it lacks details on return values, error states, or specific behavior differences from alternatives. Adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (siteId and customHeaders have descriptions, clientId does not). The description does not add meaning for clientId beyond what the schema lacks. It references client MAC but does not reinforce that clientId is required. Baseline score due to moderate coverage without additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches details for a specific Omada client, using verb 'Fetch' and resource 'specific Omada client'. It also adds that it filters the site client list in-process, which clarifies its scope. The deprecation notice does not confuse 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides to use listClients instead of this deprecated tool, and mentions getClientDetail when a client MAC is available. This provides clear when-to-use and when-not-to-use guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It states what data is returned but omits behavioral traits such as whether the client must be online, if the tool is rate-limited, or that siteId defaults to a configured site (not mentioned). Adequate but not fully 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?
A single sentence that is concise, front-loaded with key information, and contains no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no output schema, and no annotations, the description is fairly complete. It explains the tool's purpose and returned fields. However, it could improve by noting that the client must be currently connected (likely) or any other contextual limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific details beyond what the schema provides; it focuses on the output. Schema already documents clientMac as required and siteId with default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action ('Get full detail') and resource ('specific client by MAC address'), listing key data fields (connection info, IP, VLAN, signal strength, traffic stats). This distinguishes it from sibling tools like 'getClient' (likely simpler) and 'listClients' (list all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates usage when full client details are needed by MAC, but lacks explicit guidance on when to prefer this tool over alternatives (e.g., 'getClient' for summary, 'listClients' for all clients). No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool retrieves data sorted by traffic volume, but doesn't disclose read-only nature, pagination, or response format. Adequate for a simple retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that conveys the tool's purpose efficiently with 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, and the description covers its core function. Lacks details about output structure, but given no output schema, the description provides a reasonable overview.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 good field descriptions. The description adds 'sorted by traffic volume' but that pertains to output, not parameters. No additional parameter meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), resource ('most active access points'), and scope ('in a site, sorted by traffic volume'), distinguishing it from siblings 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided. The siteId parameter description hints at default behavior, but there is no comparison with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not explicitly state the operation is read-only, mention authentication needs, or disclose any side effects. The parameter description in schema mentions default site fallback, but the tool description itself lacks behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are front-loaded with the core purpose. Every word adds value, and there is no unnecessary repetition 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 and simple parameters, the description sufficiently conveys the return value structure. The mention of 'connectivity graph' is slightly vague but acceptable for a high-level overview tool. No critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters (siteId, customHeaders) having descriptions. The tool description adds no new parameter meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the site overview topology, listing specific components (device counts, client counts, connectivity graph, health status). It distinguishes from sibling dashboard tools by being a general overview, reinforced by 'Good first call'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as an initial overview ('good first call to understand what's in the network'), providing context. However, it does not explicitly exclude scenarios or mention alternatives, though the sibling list makes differentiation possible.
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 bears full burden. It states the tool retrieves top devices by memory usage, but does not disclose behavioral traits like read-only nature, sorting, limit, or response structure. It is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is clear and front-loaded. It contains no redundant or wasteful information, earning its place efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two optional parameters, no output schema, and low complexity, the description provides sufficient context for an agent to understand the tool's purpose. It could mention output format but is not strictly necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 both parameters (siteId, customHeaders) with descriptions. The tool description adds no additional parameter context beyond the schema, achieving the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), a clear resource ('top devices by memory usage'), and a context ('for a site'). It also provides a use case ('identifying memory-constrained devices'), which distinguishes 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 implies when to use it (memory constraint identification) but does not explicitly state when not to use it or provide alternatives among siblings. The context of sibling tools helps, but the description itself lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates a read operation by returning a list of devices with MAC addresses and connection details, but it does not explicitly state read-only nature, permissions required, or other behavioral traits like rate limits or side effects. 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 two sentences, front-loading the purpose and adding a brief example use case. Every sentence is informative and concise, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema. The description mentions return values (MAC addresses and connection details) but does not fully specify the output structure. It also omits error conditions, prerequisites (e.g., AP must have switch ports), or how connection details are formatted. For a moderate complexity tool, it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a clear description. The tool description does not add significant value beyond the schema; it only mentions MAC addresses and connection details, which are implied by the parameters. With full schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get wired downlink devices connected to an access point's LAN port.' It specifies the resource (wired downlink devices) and action (get), and it distinguishes well from sibling tools like getApUplinkConfig or getUplinkWiredDetail, which serve different functions.
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 the tool: 'Useful for APs with built-in switch ports (e.g. EAP615-Wall).' It implies that the tool is for APs with LAN ports acting as a switch, but it does not explicitly state when not to use it or mention alternative tools, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It lists the specific data returned (link status, speed, IP, bytes, port profile) and implies it is a read operation (get). It does not disclose any side effects, authentication requirements, or rate limits, but for a straightforward read tool, this is adequate. The description does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences long and front-loads the main purpose and output fields in the first sentence. The second sentence provides valuable sibling comparison and a usage prerequisite. Every word earns its place with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should hint at return structure. It lists the kinds of fields returned but does not specify whether the response is an array or object, nor does it mention nested objects (context signal indicates nested objects). This is a moderate gap, but the description is still informative enough for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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. The description adds value by advising to use listDevices to obtain gatewayMac, which helps the agent understand the prerequisite. The schema already explains siteId and customHeaders semantics, so the description adds marginal but useful context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it retrieves all WAN and LAN port details for a specific gateway and lists the specific fields (link status, speed, IP address, bytes, port profile). It distinguishes this tool from less detailed siblings (getGatewayWanStatus, getGatewayLanStatus), making the purpose crystal clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (when detailed port info is needed) and points to less detailed alternatives. It also advises to use listDevices to get the gatewayMac. However, it does not explicitly state when not to use it (e.g., if only wan status is needed), but the comparison to siblings implicitly covers that.
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 describes the tool as read-only ('Get') and mentions the time range, but does not explicitly state it is non-destructive, nor does it disclose authentication or rate limits. Adequate for a read tool but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: first states purpose, second adds detail, third lists use cases. The timestamp note is redundant with schema but not wasteful. Could be slightly more structured but is efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description hints at return values ('traffic volume and utilization per internet uplink'). It covers purpose, usage, and output expectation. Lacks details on pagination or time range limits, but is fairly complete for a straightforward read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters. The description adds 'start and end are Unix timestamps in seconds,' which reiterates the schema. No additional meaning beyond the schema 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?
Specific verb 'Get' and resource 'per-WAN ISP link load' clearly define the tool's purpose. The description distinguishes it from sibling tools like getGatewayWanStatus by focusing on load over a time range and mentioning traffic volume and utilization.
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?
Explicit use cases are given ('understanding load balancing behaviour, identifying saturated WAN links, and analysing failover events'), but no explicit alternative tools or when-not-to-use guidance is provided. The context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns data, implying a read operation. However, it does not disclose any potential side effects, authorization requirements, or rate limits. The description is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource, followed by return fields. Every sentence provides essential information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the return data (switch, port, speed, PoE). For a simple query tool, this is sufficient to understand what the tool provides. The sibling context is large but the description helps differentiate.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 (apMac, siteId, customHeaders) are fully described in the input schema. The description adds no additional parameter-level information 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 retrieves 'wired uplink detail for an access point' and lists specific return fields (switch, port, speed, PoE). This distinguishes it from sibling tools like getApUplinkConfig (likely wireless) and getDownlinkWiredDevices.
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 includes 'Useful for mapping physical network topology' as a hint, but does not explicitly state when to use this tool versus alternatives or provide exclusions. With many sibling tools, more guidance would be beneficial.
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 type of data (time-series) and client categories, but does not mention behavioral traits like data aggregation intervals, real-time vs historical, or authentication requirements. 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 efficiently convey purpose and return type, with no redundant information. The first sentence is action-oriented, and the second adds context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description is brief for a time-series tool. It lacks details on the response structure, pagination, or how snapshots are timestamped. While it covers essential data points, more completeness would aid agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides descriptions for 3 of 4 parameters (75% coverage). The description mentions 'over time' correlating with start/end but adds no further meaning. customHeaders parameter is undocumented in both schema and description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves client activity statistics as time-series data, specifying new, active, and disconnected clients for both wireless and wired types. This differentiates it from sibling tools like listClients or getClientDetail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes it is 'useful for monitoring client connection trends and activity patterns', implicitly guiding when to use. However, it does not explicitly state when not to use or mention alternatives among the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It describes the output in general terms but does not disclose potential side effects, error cases, pagination behavior (though page/pageSize are in schema), or any guarantees about data freshness. This is adequate but not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The first sentence states purpose and output, the second provides essential prerequisite guidance. Front-loaded, efficient, and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, so the description should explain the return value structure. It only says 'Returns which VLANs are assigned to which ports', which is vague. Combined with 5 parameters and no further details on output format, completeness is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter described. The description adds a cross-reference for switchMac ('Use listDevices to get switchMac values') but does not add significant new 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?
The description starts with a specific verb ('List') and a clear resource ('VLAN network assignments for a switch'), and specifies the output ('which VLANs are assigned to which ports, including tagged and untagged configurations'). This clearly distinguishes it from siblings like listDevices 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on a prerequisite ('Use listDevices to get switchMac values') and implies the tool is for network assignments. However, it does not list alternatives or state when not to use this tool (e.g., to list all network assignments across switches), which would strengthen the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description clearly indicates a read-only operation via 'Get' and describes the return information. It does not disclose permissions or rate limits, but for a simple read 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?
Two concise sentences that front-load the main action and return data. 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?
No output schema exists, but the description lists the key return fields. Parameters are well-documented in the schema. For a simple get operation, the description is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning to the parameters beyond what the schema already provides (e.g., apMac pattern and examples).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the specific resource 'uplink configuration for an access point'. It lists the three types of data returned, which distinguishes it from sibling tools that focus on other aspects like general config, radios, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. The context of 'uplink configuration' implies its scope, but no direct comparison with sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral burden. It does not mention permissions, side effects (likely safe as a read operation), or potential performance impact. The description is straightforward 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?
Two highly focused sentences: first lists data returned, second gives prerequisite. 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?
The description accounts for the tool's 3 parameters, prerequisite, and return scope (configuration and status fields). Without an output schema, it adequately informs the agent of what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema; it reiterates the gatewayMac prerequisite already in the schema description. No parameter details beyond schema are 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 tool's purpose: 'Fetch full configuration and status for a specific gateway' and lists key data elements (model, firmware, CPU/memory, etc.). It differentiates from sibling tools (e.g., getApDetail, getSwitchDetail) by specifying it's for gateways.
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 mentions a prerequisite: 'Use listDevices to get the gatewayMac.' While it doesn't specify when not to use this tool, the sibling context provides clear distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states this is a read operation returning specific statistics, with no mention of destructive actions. However, it does not disclose potential rate limits, authentication requirements, or performance impact, which 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, front-loaded with the core purpose, and wastes no words. It efficiently conveys the tool's function and use case.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately lists the returned statistics (link quality, signal strength, throughput, hop count). It covers the main purpose and parameter discovery via schema comments. Minor gaps include lack of error conditions or edge cases, but overall it is complete for a read-only diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema includes meaningful descriptions for apMac (including a usage hint) and siteId (referring to listSites and default config). The tool description adds no additional parameter details beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), the resource ('mesh link statistics for an access point'), and the specific output fields (backhaul link quality, signal strength, throughput, hop count). It distinguishes itself from sibling tools like getApDetail and getClient by focusing specifically on 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Useful for diagnosing mesh network performance,' which implies a usage context but does not explicitly state when to use this tool versus alternatives or provide when-not conditions. The schema hints at using listDevices and listSites for parameter discovery, but no explicit usage guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly implies a read-only operation through the verb 'Get', and it specifies the returned data. However, it does not disclose potential side effects (none expected), authentication requirements, or rate limits. The description is adequate but not enriched beyond the basic read nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences that front-load the purpose and immediately describe the return value. No unnecessary words or repetitions. 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 absence of an output schema, the description adequately describes the return value (LAG groups with member ports, mode, status). It also references a prerequisite tool. However, it could benefit from a brief contrast with sibling tools like getStackPorts to clarify when this specific tool is needed.
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 good descriptions. The description adds value by providing context for the stackId parameter ('Use getSwitchStackDetail to get the stackId') and hints about customHeaders ('Rarely needed'). This supplements the schema's information, moving beyond 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 tool's purpose: retrieving the LAG list for a switch stack. It specifies the resource ('Link Aggregation Group (LAG) list'), the action ('Get'), and the content of the response ('member ports, load balancing mode, and status'). This differentiates 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 hint ('Use getSwitchStackDetail to get the stackId') but does not explicitly state when to use this tool versus alternatives. There is no guidance on when not to use it or what scenarios are more suitable for other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes a list operation (likely read-only) but does not explicitly state it is non-destructive, safe, or what side effects might exist. The verb 'list' and the nature of returning device details imply idempotency, but more direct disclosure would improve this score.
Agents need to know what a tool does to the world before 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 action and scope, no extraneous words. Each sentence adds value: first defines purpose and output, second provides usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description lists key return fields (MAC, model, firmware version, etc.), which is mostly complete for a list tool. Lacks mention of pagination or sorting, but context signals do not indicate these are needed. The tool's complexity is moderate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 siteId and customHeaders are already documented in schema. Description adds that siteId is optional and defaults to OMADA_SITE_ID, but this is also implied by schema's description. No additional semantic value beyond 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 specifies the tool lists provisioned network devices in a site, naming device types (gateways, switches, access points) and return fields (MAC, model, firmware, etc.). Distinguishes from siblings like searchDevices and getAllDeviceBySite by focusing on adopted devices with detailed fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use MAC addresses from this response as input to detail tools (getGatewayDetail, etc.), providing a clear downstream usage context. However, it does not mention when not to use this tool or alternatives such as searchDevices for filtered queries.
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 the full burden. It discloses the sorted nature and return fields, but does not mention potential limits on number of clients, pagination, or authentication requirements. The read-only nature is implied but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are concise and front-loaded with the primary action. Every sentence adds value without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers return fields and the overall purpose. However, it lacks details on result limits or sorting order, which would be helpful for a complete understanding. The context is adequate for a simple dashboard endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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. The description does not add significant new meaning beyond the schema, such as clarifying the role of siteId in determining the default site.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 the tool gets the most active clients in a site, sorted by total traffic. Specifies return fields and distinguishes from sibling tools like getClient or listClients by focusing on top traffic clients as a dashboard overview.
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?
Describes the tool as a dashboard endpoint for a quick overview, implying it's for summary rather than detailed client info. However, it does not explicitly exclude use cases or suggest alternatives like getClientDetail for more detailed client data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool returns specific fields and implies read-only behavior by listing devices, but does not mention side effects, error handling, or permissions. Adequate but with gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the key purpose, no unnecessary words. 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?
Despite no output schema or annotations, the description covers purpose, return fields, and context. It could mention pagination or error cases, but for a simple list tool it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes both parameters. The description adds no new information about parameters beyond what the schema provides; it merely implies siteId's role. 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 specifies the tool lists devices discovered but not adopted, distinguishing it from siblings like listDevices which likely list adopted devices. It also mentions the returned fields (device type, MAC, IP, model).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to find devices waiting to be provisioned. However, it does not explicitly state when not to use it or mention alternatives, but the scope is well-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 must disclose behavioral traits. It implies a read-only operation by saying 'Fetch', but does not mention authorization, rate limits, side effects, or response volume. 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?
The description is two sentences: the first lists what the tool fetches (front-loaded purpose), the second provides a key 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?
Without an output schema, the description lists the expected return fields (model, firmware, etc.), which is sufficient for a fetch operation. It also covers prerequisite steps for parameters. Minor gap: no mention of response format (e.g., JSON).
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 how to obtain the apMac (via listDevices) and siteId (via listSites, with default fallback), going beyond the schema's raw descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('full configuration and status for a specific access point'), and lists concrete fields (model, firmware, etc.). This clearly distinguishes it from sibling tools like getApGeneralConfig or getApRadios, which fetch only partial data.
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 guides the user to 'Use listDevices to get the apMac', which is a prerequisite. However, it does not contrast with alternatives or state exclusions (e.g., when not to use).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool returns stored configuration (not runtime), but lacks details on error handling, authentication requirements, or rate limits. With no annotations, the description carries full burden; more behavioral cues 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?
Two sentences: first defines purpose and contents, second provides usage guidance. No redundant phrases, efficiently communicates 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?
Lists several returned fields, enough to understand scope. No output schema exists, but the description gives a reasonable overview. Could mention error cases or that return is a JSON object with nested parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 3 parameters (100% coverage). Description adds value by referencing help tools for apMac (listDevices) and siteId (listSites), going beyond the schema's format descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get' and resource 'general configuration for an access point', listing specific returned fields. Distinguishes from siblings like getApDetail by noting it returns stored configuration vs runtime status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using getApDetail for runtime status, providing a direct alternative. While it doesn't list exhaustive when-not-to-use scenarios, the single contrast is sufficient for clear differentiation.
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?
Lists specific return values (WAN IP, DNS, uptime, etc.) indicating read-only nature. No annotations present, so description carries full burden; missing details on errors or rate limits but sufficient for typical use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines purpose, second provides actionable prerequisite. No redundancy, front-loaded with key info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists key return fields. Implies multiple WAN ports but doesn't specify output format (list vs object). Adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions; description adds no new param meaning beyond schema (e.g., the prerequisite is already in gatewayMac 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?
Clear verb 'Get' and resource 'WAN port status and connectivity information'. Distinguishes from siblings like getGatewayLanStatus and getGatewayDetail by specifying WAN focus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisite 'Use listDevices to find the gatewayMac.', but lacks when-not-to-use guidance or comparison with 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. The tool reads data without modification, but the description does not explicitly state it is read-only nor mention any behavioral quirks like rate limits or permissions. The 'Fetch' verb implies safety, but transparency could be improved.
Agents need to know what a tool does to the world before 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. The first covers purpose and scope, the second provides a critical prerequisite. No redundant information, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (detailed switch data) and the absence of an output schema, the description lists the fields returned (model, firmware, CPU/memory, port states, etc.), which is highly informative. It also notes the prerequisite and optional siteId. This is sufficient for an agent to understand the tool's output.
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 parameters are well-documented in the schema. The description adds value by linking switchMac to listDevices and siteId to listSites with a default behavior note. This context aids correct parameter usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and clearly enumerates the resources retrieved (model, firmware, CPU/memory, port states, PoE usage, VLAN config, STP status). It distinguishes from sibling tools like getSwitchGeneralConfig and getApDetail by stating it retrieves full configuration and status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use listDevices to obtain the switchMac parameter, providing a clear prerequisite. While it doesn't contrast with alternative switch detail tools, the guidance is sufficient for correct invocation.
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 it returns a list of client details, but does not disclose potential pagination, rate limits, or performance characteristics. Additional context about response size limits 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?
Two sentences deliver the purpose and return details efficiently with no redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 optional params, no output schema), the description covers purpose, input semantics, and output fields. It does not explain pagination or default behavior for large lists, but is adequate for a listing 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 coverage is 100%, so the baseline is 3. The description adds value by explaining that siteId is optional and defaults to OMADA_SITE_ID, and that customHeaders are rarely needed. This clarifies usage 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?
Description clearly states the tool lists all network clients (wired and wireless) connected to a site, and specifies the returned details (MAC, IP, hostname, etc.). It distinguishes itself from sibling tools like getClient (specific client) and listClientsActivity (activity log).
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 suggests use cases: 'audit connected devices or find a specific client by name or MAC.' It does not explicitly mention when not to use, but the context is clear. However, it could mention alternative tools like getClient for a single client detail.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses deprecation, that the endpoint returns stored results (not real-time), and lists the types of data returned. It does not discuss authentication or rate limits, but the read-only nature is implied by 'Get' and the lack of side effects mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loading deprecation and purpose, then data content, then prerequisite. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description enumerates the kind of data returned (neighboring networks, per-channel utilization, interference, RSSI), which suffices. Parameter descriptions are covered by schema. The tool's role among 80+ siblings is clear from its name and description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no significant meaning beyond the schema descriptions; it mentions using listDevices to find AP MACs, which is already in the schema for apMac. No additional parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get) and resource (last RF scan results for an access point), specifies it is deprecated, and lists the data returned (neighboring networks, per-channel utilization, interference, RSSI). It distinguishes itself from sibling tools by focusing on RF scan results, which is unique among the sibling list.
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 mentions using triggerRfScan first to initiate a fresh scan, and notes this endpoint returns the most recent stored results. Also flags deprecation, which advises caution. Missing explicit when-not-to-use or alternative tool references, but the prerequisite is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description honestly discloses the inclusive behavior. Lacks discussion of potential performance 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?
Two efficient sentences, front-loaded with purpose and key differentiator. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description is sufficient for a list-all tool. Could add note on pagination but not necessary given sibling tools.
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 has 100% coverage; description adds useful context like default siteId behavior and customHeaders rarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 gets all devices in a site including offline/disconnected, and explicitly differentiates from listDevices.
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 says when to use (auditing full inventory) and contrasts with listDevices for active-only.
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 bears full burden. It discloses the tool is a read-only operation returning stored results, which is key. However, it lacks details on error handling (e.g., if no prior test exists) or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. Purpose is front-loaded, and critical usage guidance follows immediately.
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?
Provides sufficient context for a simple read tool: what it returns, prerequisites (triggerSpeedTest), and param guidance. Lacks output format details but given no output schema, description could be slightly more 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 covers all parameters (100%), but description adds value by explaining the apMac format and suggesting listDevices, and clarifying siteId default behavior and cross-reference to listSites. This helps agent use parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 speed test results for an access point' with specific metrics (upload/download throughput). It differentiates from sibling tools like getApDetail by focusing on speed test results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use triggerSpeedTest first to initiate a new test, clarifying that this tool returns stored results. Gives clear when-to-use and a direct alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly describes a read operation ('Get') and details the return fields (band, channel, transmit power, channel width, enabled SSIDs). While it does not mention error conditions or authorization needs, the description is transparent enough about the tool's behavior for a straightforward get 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 long, front-loading the main purpose in the first sentence and providing sibling differentiation in the second. No extraneous information is present; every sentence serves a clear purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately summarizes the return fields (per-radio settings for 2.4GHz, 5GHz, 6GHz including band, channel, etc.). It explains the tool's scope, mentions prerequisites (apMac), and distinguishes from a sibling. For a tool with 3 parameters and moderate complexity, the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all three parameters have descriptions). The description adds contextual value by suggesting how to obtain the apMac value ('Use listDevices') and noting that siteId defaults to the configured site. This goes beyond the schema alone, justifying a score above 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 'Get per-radio configuration for an access point' with a specific verb and resource. It lists the included settings (band, channel, etc.) and explicitly distinguishes from the sibling tool getApRadios, which returns runtime status instead of configuration.
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: 'Use getApRadios for runtime radio status; this returns configuration.' It also hints at prerequisite tooling for the apMac parameter ('Use listDevices to find AP MACs'), helping the agent choose correctly between similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

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