woow_emqx_mcp_server

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation5/5
Each tool targets a distinct resource and action, with clear separation even among similar metrics tools (broker_stats vs metrics_current vs metrics_history). Descriptions explicitly note overlaps and guide selection, so misselection is unlikely.
Naming Consistency4/5
Most tools follow a consistent emqx_<verb>_<noun> pattern (emqx_list_clients, emqx_kick_client, emqx_delete_retained), but a few deviate with noun-verb ordering (emqx_client_subscribe) or generic verbs like manage (emqx_manage_authn_users). Still predictable and readable overall.
Tool Count2/5
39 tools is far above the typical well-scoped range and likely overwhelms agents. While the EMQX domain is broad, the granularity (e.g., separate metrics_current and metrics_history) could be consolidated without loss of function.
Completeness4/5
The surface covers major EMQX workflows: monitoring, clients, subscriptions, retained messages, rules, traces, authn/authz, and bans. Minor gaps exist, such as no update for authn users and no retain flag on publish, but these are workable and do not break core use cases.
Average 4.2/5 across 39 of 39 tools scored. Lowest: 3.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 22 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
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

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds behavioral context by noting that it returns 'currently barred' items and includes 'expiry times', which is useful but minimal. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero fluff. It efficiently conveys the purpose and key detail (expiry times) in just eight words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless read-only list tool with an output schema present, the description is adequate. It specifies the scope ('currently barred') and a key output detail ('expiry times'). It does not need to explain return format because output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty object). Per rubric, a baseline of 4 is appropriate when there are no params. The description does not need to explain parameter semantics since none exist.
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 'Everything currently barred from connecting, with expiry times' clearly identifies the resource as banned clients and the action as listing them. It distinguishes from sibling tools like emqx_list_clients (connected clients) and emqx_ban/unban. Though the verb 'list' is not explicit in the description, the title and context make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention related tools like emqx_ban or emqx_unban, nor does it state any prerequisites or preferences. The usage is entirely implied by the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable domain context about retained messages as 'last known value' and the risk of stale entries causing ghost entities. This helps interpret results but does not disclose pagination behavior or return completeness beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the core concept, but the first sentence is a grammatically awkward fragment ('Retained messages the broker is holding.') and the ghost entity warning, while useful, is a bit tangential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with full annotations and an output schema, the description adequately explains what retained messages are and a key pitfall. It could explicitly state that it lists all retained messages with pagination, but the title and schema already imply this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for both page and limit, so the description adds no extra parameter semantics. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (retained messages) and the context (broker holding them), making the listing purpose clear. However, the opening is a noun phrase rather than an explicit verb phrase, and it does not differentiate from sibling tools like emqx_get_retained or emqx_delete_retained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The mention of ghost entities implies a use case (checking stale retained messages) but does not state when to choose this over emqx_get_retained or emqx_list_topics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral detail beyond the rich annotations (readOnly, openWorld, idempotent, non-destructive) and schema. It does not mention filtering, response shape, or side effects, and 'first place to look' is usage guidance, not behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded phrase with zero filler—concise, memorable, and every word earns its place. It is a model of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with full schema coverage, strong annotations, and an output schema, the description provides sufficient usage context. It could explain the meaning of 'alarms' or return structure, but the output schema and parameter schema cover those aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter active_only is fully documented in the schema with a clear description ('True for currently firing alarms, False for history'). The tool description adds no additional parameter context, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (broker alarms) and positions it as a diagnostic entry point, which distinguishes it from sibling diagnostics. However, it relies on the tool name for the verb 'list' rather than explicitly stating the action.
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 first place to look when something feels wrong' clearly indicates when to use this tool for troubleshooting. It does not name alternatives or exclusion criteria, preventing a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's '[DESTRUCTIVE]' prefix duplicates that. It adds the behavioral outcome that the client 'may connect again', but does not disclose other traits such as idempotency (already annotated) or what happens if the ban does not exist. The extra context is minimal but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the destructive warning and immediately states the action and its effect. There is zero redundancy or wasted words, and it is appropriately sized for a simple two-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with full schema and annotations providing safety and parameter details. The description explains the core purpose and outcome, and an output schema handles return values. Missing context includes explicit guidance on matching subject_type to the original ban and potential error conditions, but these are partially covered by the schema. Overall, it is adequately complete for a low-complexity destructive action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters fully described in the input schema (who as 'The exact banned value' and subject_type as an enum with a clarifying note). The description adds no parameter-specific meaning beyond the tool's purpose, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Lift a ban so the client may connect again' uses a specific verb (Lift) and resource (ban) and clearly distinguishes it from siblings like emqx_ban (which creates bans) and emqx_list_banned (which lists bans). The outcome is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like emqx_ban or emqx_list_banned. It implies usage by saying 'Lift a ban' but does not explicitly state prerequisites, such as needing to know the exact banned value and subject_type, nor does it mention that this should be used to reverse a specific ban.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the metrics measured, but does not disclose behavioral details such as whether values are instantaneous snapshots, how 'rate' is computed, or what the response structure looks like beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with parenthetical specifics. Every word contributes value, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only metrics tool with no parameters and strong annotations, the description provides sufficient detail about the measured metrics. The output schema (though not shown) would cover return values. A minor gap is the ambiguity of 'dropped' and 'rate' without further context, but overall it is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema fully covers parameter semantics. The description does not need to add parameter information, and the baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as current throughput gauges and specifies the metric types (messages/s in/out, dropped, rate). It distinguishes from sibling tools like emqx_metrics_history via the word 'current', but lacks an explicit verb such as 'get' or 'retrieve'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'current' implies this tool is for real-time metrics, not historical analysis, but the description does not explicitly say when to use it vs alternatives like emqx_metrics_history or emqx_broker_stats. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds a sense of comprehensive data ('Everything') but does not disclose behavior on missing nodes, response size, or potential errors. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence ('Everything EMQX knows about one node.') with no wasted words. It is concise and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, rich annotations (read-only, idempotent), and a well-documented parameter, the description is adequate for a simple one-parameter tool. The main gap is usage guidance, but the overall structured context is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the node parameter is described with precision: exact format, an example, and the source (emqx_cluster_status). This goes well beyond a bare string type, providing clear semantics. The main description adds nothing, but the schema fully compensates.
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 'Everything EMQX knows about one node' clearly indicates a read-only retrieval of comprehensive details for a single node. It distinguishes from siblings like emqx_cluster_status by focusing on one node rather than the cluster, though it lacks an explicit verb like 'get' or 'fetch'.
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 itself provides no usage guidance, but the parameter schema states the node name must be 'exactly as emqx_cluster_status reports it', implying a prerequisite to first list cluster status. There is no explicit mention of when to use this tool over alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the detail that results include status and expiry, but does not disclose behavioral aspects like whether expired traces are included, pagination, or ordering. It goes slightly beyond annotations but not substantially.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that contains no filler. Every phrase contributes meaning: 'packet traces', 'defined on the broker', and 'with status and expiry'. It is appropriately sized for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only list tool with an existing output schema, the description covers the core semantics. It clearly states what is being listed and highlights key included fields. The main gap is the absence of any mention of the full scope (e.g., 'all' traces) or edge cases, but these are not critical for such a simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially complete. The description does not need to explain parameters. The baseline for zero parameters is 4, and no additional parameter semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (packet traces on the broker) and the operation type via the title, adding specific detail about the returned data (status and expiry). It effectively distinguishes this from sibling trace tools like emqx_get_trace_log, emqx_create_trace, and emqx_delete_trace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention that it lists all traces or when to use emqx_get_trace_log for log content. The description is purely declarative and lacks any contextual pointers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds the contextual detail that data is over a 'recent window' but does not disclose other behavioral traits such as output format or data granularity. With annotations covering safety, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences that define the tool and provide usage context. Every word earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one well-documented parameter, output schema, and rich annotations, the description provides sufficient context. It could have explicitly differentiated itself from emqx_metrics_current, but the recent-window framing and use cases make the tool's role clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description of the latest_seconds parameter. The description itself does not add further meaning to the parameter, 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 tool provides 'Time-series metrics over a recent window' and gives concrete use cases (spike detection, connection drops, incident correlation). While it lacks an imperative verb like 'Get', the resource and scope are specific and it distinguishes from sibling tools like emqx_metrics_current by focusing on historical 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 states when to use this tool: to answer questions about spikes, drops, or correlate incidents with broker load. It does not directly name alternatives or state when not to use it, but the use cases are clear and the sibling list provides context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only, idempotent, non-destructive operation. The description adds useful context about what the returned settings cover: unmatched-rule behavior, denial impact on connections, and cache settings. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core concept ('Global authorization behaviour') and uses a colon to efficiently enumerate three specific aspects. Every phrase earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read tool with a rich output schema and clear annotations, the description provides sufficient context to understand what the tool offers. It does not need to explain return values because the output schema exists and handles that detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter-level explanation is unnecessary. The description focuses on the meaningful content of the settings, which is appropriate given the empty 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 clearly identifies the tool as exposing global authorization behavior, including default actions and cache settings. It lacks an explicit verb like 'get' or 'view,' but the scope is specific and distinguishes it from sibling tools like emqx_list_authz_sources and emqx_manage_authz_rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for reading global authorization settings rather than managing specific sources or rules, but it does not explicitly state when to use it versus alternatives. No exclusions or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable context: the device stops receiving the topic immediately and has no way to tell why. This goes beyond the annotations by explaining the immediate effect and the lack of client notification, which is important behavioral information for an agent deciding whether to call this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long and front-loaded with a [DESTRUCTIVE] tag. It communicates the purpose and a key behavioral consequence without any filler. Every sentence earns its place, making it highly efficient 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 the tool's low complexity (2 parameters, no nested objects), the annotations (destructive, idempotent, openWorld), the complete schema descriptions, and the presence of an output schema, the description covers the essential behavioral context. It could add a note about idempotency or edge cases like unsubscribing from a non-existent subscription, but these are not critical for basic usage. Overall, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides clear descriptions for both parameters: topic ('Exact topic filter to remove.') and clientid ('Client id to act for.'). Schema coverage is 100%, so the description does not need to add parameter details. The description's phrase 'on its behalf' slightly reinforces the clientid semantics but does not materially improve on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Remove a subscription from a client on its behalf.' This distinguishes it from sibling tools like emqx_client_subscribe (which adds a subscription) and emqx_kick_client (which disconnects a client). The verb 'Remove' and the resource 'subscription' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool—when you need to remove a client's subscription to a topic. However, it does not explicitly mention alternatives or exclusions. For example, it does not say 'To add a subscription, use emqx_client_subscribe' or clarify when to use this instead of emqx_kick_client. The usage context is implied but not fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by specifying the return includes 'keepalive, in-flight queue, protocol, subscriptions count, connect and disconnect timestamps', conveying that it provides comprehensive session state rather than a summary. This complements the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff; it front-loads the core purpose and packs a list of relevant fields. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one parameter, full schema coverage, rich annotations, and an output schema available, the description is sufficient to understand what the tool does. It does not cover error behavior (e.g., unknown client), but that is likely handled by the output schema, so completeness is high but not maximal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the parameter clientid already has a clear description ('Exact client id, as returned by emqx_list_clients'), and the tool description adds no further parameter-specific semantics. The baseline of 3 applies because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Full session detail for one client', clearly identifying the tool as a single-client lookup. It lists specific data fields (keepalive, in-flight queue, protocol, subscriptions count, timestamps), distinguishing it from sibling tools like emqx_list_clients or emqx_client_subscriptions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for one client' implies the tool is for single-client detail, but it does not explicitly state when to use it instead of sibling tools. No alternatives or exclusions are mentioned, so guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations by disclosing that results are ordered and that the ordering is semantically meaningful ('the first source that returns allow or deny wins'). This enriches the agent's understanding of the tool's behavioral implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences, with the critical detail about evaluation order front-loaded. Every word adds value, and there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters), the presence of a full output schema, and comprehensive annotations indicating a safe read-only operation, the description is complete. The only additional behavioral nuance (order matters) is included, so the agent has all needed context to invoke and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric the baseline score is 4. There are no parameter semantics to clarify, and the description appropriately does not attempt to document parameters that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (authorization sources) and the key concept of evaluation order, which distinguishes it from sibling tools like authz settings or rules. However, it lacks an explicit verb like 'list' in the description itself, relying on the tool name/title for that, so it falls just short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is used to view authorization sources and emphasizes that order is critical for determining authorization outcomes, giving some contextual usage guidance. However, it does not explicitly state when to prefer this over other authz-related tools or provide exclusions, so it is only minimally viable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=false and destructiveHint=true, so the agent knows this is mutating and potentially destructive. The description adds that operations are create/delete/read and specifies the resource is built-in-database. However, it does not detail consequences of delete, permission requirements, or side effects beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. No redundant phrases; every word serves to define scope and operations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present and annotations covering safety profile, the description provides adequate context for a 4-parameter tool. It identifies the specific resource type and available operations. Minor gap: no mention of parameter interactions (e.g., which params are needed for which operation), but schema descriptions likely handle that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions with 100% coverage. The description contributes by enumerating valid operations (create, delete, read), which the operation parameter references ('see the tool description'). This adds meaning beyond the schema's generic 'Action to perform'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Read and write built-in-database ACL rules that decide which topics a user or client may publish to and subscribe to.' This specifies the verb (read/write), resource (built-in-database ACL rules), and subject (user/client topic permissions). It also enumerates operations (create, delete, read), distinguishing it from sibling authz tools that manage sources or settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Operations enabled on this server: create, delete, read,' which indicates what actions can be performed but does not explicitly state when to use this tool versus alternatives like emqx_authz_settings or emqx_list_authz_sources. The context of 'built-in-database ACL rules' implies usage for that specific rule store, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds a key behavioral detail: the device is unaware of the subscription and it will not be recreated after a clean-session reconnect, which clarifies the side-effect nature beyond the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences: the first states the operation, the second adds an important caveat. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the rich schema and annotations, covers the essential behavioral nuance (device unaware, clean-session behavior). Since an output schema exists, return values need not be explained, making the description sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (clientid, topic, qos) have descriptions in the schema, giving 100% coverage. The description adds no additional parameter semantics beyond the action, 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 'Add a subscription to a client on its behalf,' which is a specific verb+resource. This distinguishes it from the sibling 'emqx_client_unsubscribe' which does the reverse action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context about the behavior (device unaware, clean-session reconnect) but does not explicitly state when to use this tool versus alternatives like emqx_client_unsubscribe or emqx_publish. The usage guidance is implied rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds interpretive value beyond annotations by explaining what matched=0 means, helping the agent reason about rule health. No contradictions or missing safety-relevant behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: one sentence defines the output, and a second sentence offers a practical interpretation tip. Every word earns its place with no fluff or repetition of schema/annotation content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only metrics tool with an output schema present, the description is sufficiently complete. It conveys what the counters are and how to interpret a common edge case, so an agent can confidently select and invoke the tool without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter rule_id, including a cross-reference to emqx_list_rules. The description adds no additional parameter-level detail, so it does not exceed the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns match, pass, and failure counters for a single rule, which distinguishes it from broader EMQX metrics tools or rule listing tools. It lacks an explicit verb like 'get' but the noun-phrase style is unambiguous and specific.
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 a key diagnostic use case: a rule with matched=0 indicates no matching traffic, likely due to a FROM topic filter mismatch. This provides useful context for when to inspect metrics, though it does not explicitly exclude alternatives or name sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds beyond annotations by specifying that actions are bridges attached to rules and that the output includes health, which is useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise phrase that conveys the essential information without unnecessary words. It is front-loaded and perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters, output schema present, strong annotations), the description is complete. It clarifies the resource type, scope, and health aspect, making it fully adequate for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty. The baseline for zero-parameter tools is 4, and the description does not need to add parameter details. It adds no param info, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists outbound actions (bridges) attached to rules, including their health. This verb+resource+scope structure distinguishes it from siblings like emqx_list_rules and emqx_list_connectors.
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 when-to-use or alternative guidance is provided. The description does not mention when to prefer this over sibling tools like emqx_list_connectors or emqx_list_rules, leaving the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive. The description adds that the tool provides cluster-wide node information, which is helpful, but it does not explain behavior such as whether the output is aggregated or how resource use is calculated. This is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states what the tool provides, and the second gives usage guidance. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple, parameterless tool with an output schema and strong annotations. The description sufficiently covers when to use it and what it reveals, making it complete for an agent to select and invoke appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to document. Per the rubric, a baseline of 4 is appropriate because no parameter clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (EMQX cluster nodes) and the contents (version, uptime, resource use), but lacks an explicit verb like 'list' or 'returns'. It does not explicitly distinguish itself from sibling tools, though 'cluster status' implies a cluster-wide view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to start here: for health or version questions, and before any node-specific call to learn valid node names. This gives clear usage context and implies that node-specific calls should be used for deeper 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?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds meaningful behavioral context: it returns connector connection health and explains that the list may be empty on OSS due to enterprise licensing. This goes beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no fluff. The first sentence front-loads the core purpose, and the second adds essential caveat about OSS. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool with rich annotations and an output schema present, the description covers the essential points: what is listed, what health info is included, and a critical usage caveat (OSS vs enterprise). No further context is needed for a tool of this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the baseline is 4 per the rubric. The description correctly omits parameter details since there are none to document.
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 title 'List EMQX Connectors' clearly states the action and resource, and the description adds specificity by mentioning 'data-integration connectors and their connection health'. However, the description itself is a noun phrase rather than a verb phrase, and it doesn't explicitly distinguish this from sibling list tools like emqx_list_actions or emqx_list_clients, though the focus on connectors is distinct enough.
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 useful context for when to use the tool and how to interpret results: it explains that open-source EMQX ships only HTTP and MQTT connectors, so an empty list is normal on OSS. This sets expectations clearly, though it doesn't explicitly mention alternatives or exclusions relative to other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior, so the description adds useful context about what is exposed (bind addresses and running state, with specific port numbers). This goes beyond the structured annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both meaningful. The first states what the tool lists; the second provides a concrete diagnostic use case. No wasted words, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with no parameters and an output schema, the description covers the key content (bind addresses, running state) and typical use case. It is complete given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema is empty, so the description does not need to explain parameter meanings. The baseline for 0-parameter tools is 4, and the description adds context about what the tool returns, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (listeners) and what information is provided (bind addresses, running state). It distinguishes from siblings by focusing specifically on listener status, but it lacks an explicit verb in the description itself (the verb appears in the title and tool name).
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 second sentence gives explicit guidance on when to use this tool: to confirm specific ports (1883, 8883, 8083/8084) are up before blaming a device. This is a clear use case, though it does not mention alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds context about what rules are and their role, but does not detail pagination behavior or return structure beyond that. It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded, with two sentences that convey purpose and context. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations are rich, the description is complete enough for a list operation. It explains what rules are and the list content, though it doesn't cover edge cases like empty results or pagination details, which are less critical for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for page, limit, and enabled_only. The description does not add additional parameter semantics beyond the schema, but the schema already fully documents them, 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 it lists rule-engine rules with their SQL and enabled state, using a specific verb ('list') and resource ('EMQX rules'). It distinguishes from siblings like emqx_list_actions or emqx_get_rule_metrics by focusing on the rules list itself.
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 the purpose of rules ('forward or reshapes messages without any code') and gives examples, providing context for when to use this tool. However, it does not explicitly mention alternatives or exclusions, 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?
Annotations already indicate this is a write operation without destructive effects. The description adds the efficiency detail of 'one round trip' but does not disclose behavior like partial failures, ordering, or atomicity for the batch. With annotations present, this is adequate but not richly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and the second sentence provides actionable guidance. There is no wasted language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, when to use it, and provides an example scenario. The schema documents constraints like maxItems and required fields. While it does not mention atomicity or error semantics, the presence of an output schema and the simplicity of operation make this sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add any parameter-level information beyond the schema. The schema itself documents each field (topic, payload, qos, retain) clearly, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool publishes a batch of MQTT messages in one round trip, with a specific verb and resource. It also distinguishes itself from the sibling emqx_publish by explicitly recommending this tool for seeding multiple topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to prefer this over many emqx_publish calls when seeding several topics, giving a concrete example. This clearly communicates when to use the tool and the alternative, even if it doesn't list exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, idempotent behavior. The description adds useful diagnostic context (correlating with publish topic mismatches) and notes QoS is included, which goes beyond structured metadata without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose, followed by a practical usage tip. Every word earns its place 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?
With a simple one-parameter tool, full schema coverage, and an output schema present, the description sufficiently covers the what and when. The diagnostic context rounds out the tool's role without needing extensive elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the clientid parameter as 'Exact client id.' The description adds only that it refers to one client, which is already implied. No additional semantic detail is provided beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns topics a single client is subscribed to, including QoS. This directly distinguishes it from sibling tools like emqx_list_subscriptions which likely covers all clients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit use case: diagnosing a device not receiving messages, and hints at the likely cause (subscription filter mismatch). However, it does not explicitly mention alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds valuable behavior that found=false is an ordinary answer, not an error, which is not visible in the annotations. This helps prevent misinterpretation of the most likely edge case.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the action and resource immediately, and the second adds the most important behavioral nuance. Every word earns its place with no repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-topic read tool with one parameter, comprehensive annotations, and an output schema, the description is complete. The found=false clarification addresses the only likely confusion, making the tool actionable without further documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema description covers the 'topic' parameter fully (with an example), and the tool description does not add additional meaning beyond restating 'one topic.' With 100% schema coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies the resource as 'the retained message stored for one topic,' which clearly distinguishes it from sibling tools like emqx_list_retained (listing all retained messages) or emqx_delete_retained (deleting). The scope is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for reading a single topic's retained message, which implies it should be used when you need one specific value rather than a list. However, it does not explicitly name alternative tools or state when not to use it, missing the full 'when/alternatives' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by specifying that it returns 'every subscription in the cluster' (cluster-wide scope) and explaining the powerful match_topic behavior. This goes beyond the annotation defaults without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The first sentence front-loads the core purpose, and the second delivers the most valuable filter behavior. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich schema covering all parameters, annotations providing safety metadata, and an output schema present, the description does not need to cover pagination or return details. The description's cluster-wide scope and match_topic emphasis round out the tool's purpose sufficiently for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% description coverage for all six parameters, including a detailed explanation for match_topic. The description's match_topic sentence is essentially a paraphrase of the schema text, so it adds no new semantic 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 opens with 'Every subscription in the cluster, with filters,' which clearly states the verb (list) and resource (subscriptions) plus the cluster-wide scope. This distinguishes it from siblings like emqx_client_subscriptions, which are client-specific, and highlights the unique match_topic capability.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by noting that match_topic should be used to determine which subscribers receive a message on a concrete topic. It does not explicitly name alternatives or exclusions, but the cluster-wide scope and the special callout for match_topic provide practical guidance for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context that only topics with an active route (subscriber) are listed, and absence indicates zero subscriptions. This clarifies a non-obvious behavioral trait beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver the core definition and a clarifying diagnostic note, with no filler. The description is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with an output schema and complete parameter documentation, the description explains the essential semantic (route = at least one subscriber) that the agent needs to interpret results correctly. It is complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (page, limit, topic) are already fully described in the schema with defaults and constraints, so schema coverage is 100%. The description provides no additional parameter-level meaning beyond what the schema already documents, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description defines the resource as 'topics that currently have a route' and equates that with 'at least one subscriber', making the tool's function clear. It builds on the title's verb 'List' to convey the exact scope and distinguishes it from related tools like subscription listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a diagnostic scenario: a topic missing means nobody is subscribed, which is a common reason messages vanish. This implies when to use the tool, though it doesn't explicitly name alternatives or exclude sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, but the description adds the concrete statement 'Nothing is saved' and details the report contents ('whether the event would match and what columns the rule would emit'). This provides useful behavioral context beyond the safety flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action and non-save guarantee, followed by practical usage. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple dry-run tool with full schema coverage and an output schema present, the description covers purpose, safety, usage, and result behavior. It is complete and leaves no critical questions unanswered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need 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 three parameters (sql, topic, payload) are already well-documented. The description adds no additional parameter-specific semantics beyond calling it a 'sample event', 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 starts with a specific verb+resource 'Dry-run rule SQL' and clarifies scope ('against a sample event'), making it clear what the tool does. It also distinguishes itself from siblings like emqx_list_rules or emqx_publish by focusing on pre-creation validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to check a rule before creating it', providing a clear when-to-use context. It doesn't mention when-not-to-use or name alternatives, but the guidance is unambiguous and sufficient for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include destructiveHint=true, and the description reinforces it with '[DESTRUCTIVE]'. It adds context beyond annotations: persistence, expiration, and how to lift the ban. However, it does not clarify whether existing connections are terminated, which is a minor transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the destructive warning and core action. Every sentence adds value: the persistence note and the contrast with emqx_kick_client are both necessary for correct tool selection.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence 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 mutation tool with full annotation coverage and an output schema, the description covers the essential behavior: blocking, persistence, and reversal. It does not explicitly mention the effect on existing connections, but the provided information is largely sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% parameter coverage with detailed descriptions (e.g., who, until, reason, subject_type). The description adds no additional parameter-specific meaning beyond what the schema already states, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Block a client id, username or IP from connecting,' which is specific and resource-oriented. It also distinguishes from the sibling tool emqx_kick_client by explaining the persistence, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly contrasts with emqx_kick_client: 'Unlike emqx_kick_client this persists' and references emqx_unban as the way to lift the ban. This gives the agent clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds semantic context by explaining the meaning of an empty authenticator chain, which helps the agent interpret results. It does not disclose any other behaviors (e.g., pagination, default limits), but for a simple no-parameter read-only tool, the added context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences (the first a noun phrase) plus a clear troubleshooting note. Every word earns its place, and the most actionable guidance ('Check this first...') is immediately visible. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no input parameters and an output schema (indicated by context), the description covers the key aspects: what the output represents, when to use it, and how to interpret the result. It is complete for its complexity and integrates well with sibling tools by providing a unique diagnostic role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema description coverage is 100% vacuously. The baseline for 0-parameter tools is 4, as there is no parameter information to provide. The description adds no parameter semantics because none are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The title clearly says 'List EMQX Authenticators', and the description specifies the resource and output: 'The authenticator chain and each authenticator's status.' However, the description itself lacks an explicit verb, relying on the tool name/title to convey the action. It does distinguish from siblings by focusing on authentication (authn) rather than authorization (authz) or other resources.
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?
Provides explicit when-to-use guidance: 'Check this first when devices cannot connect: an empty chain means EMQX has no user table, so every credential is rejected.' This gives clear diagnostic context and implies a troubleshooting workflow. It differentiates from other list tools by positioning itself as the first check for connection failures.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral information beyond the annotations: it warns that disabling a rule 'silently stops whatever pipeline depends on it' and advises confirming the downstream system. This complements the destructiveHint and readOnlyHint annotations without contradicting them, providing actionable safety context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, containing only two sentences that deliver the core purpose and a critical warning. The '[DESTRUCTIVE]' prefix front-loads the risk, and every sentence earns its place without superfluous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 parameters, no nested objects), and the description covers the essential purpose and the key risk. An output schema is available to describe return values, so the description does not need to explain them. It lacks minor details like behavior on nonexistent rule, but overall it is sufficiently complete for a toggle action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters already well-described in the schema (e.g., 'True to switch the rule on, False to switch it off'). The description does not add additional parameter-level meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Switch a rule on or off') with a specific verb and resource. It distinguishes from sibling tools like emqx_list_rules and emqx_get_rule_metrics by focusing on enabling/disabling rather than listing or monitoring.
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 about when to use the tool (to toggle a rule) and adds a critical caution about disabling rules affecting downstream pipelines. It does not explicitly mention alternatives, but the context is sufficient for an agent to infer the tool's role. A score of 4 reflects clear usage context without explicit when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: it covers the entire cluster, provides live counters, and notes a performance advantage (cheaper). This goes beyond the structured metadata without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, extremely concise, and front-loaded with the core purpose ('Live counters for the whole cluster'). The second sentence reinforces the use case and cost benefit. There is no wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters), rich annotations, and the presence of an output schema, the description is complete. It explains what the tool does, why it exists (cost benefit), and the cluster-wide scope. No critical information is missing for the agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by default. The description does not need to explain parameters, and it doesn't. The baseline for 0-param tools is 4, and the description adds no parameter info but also has no missing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides 'live counters for the whole cluster' with specific examples ('how many devices are online' and 'how many subscriptions exist'). It distinguishes itself from sibling tools like emqx_list_clients and emqx_list_subscriptions by highlighting its aggregate, cluster-wide nature and cost efficiency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly indicates when to use the tool: when you need cluster-level counts ('how many devices are online', 'how many subscriptions exist') and contrasts it with listing clients ('cheaper than listing clients'). It does not mention other alternatives like emqx_metrics_current or emqx_prometheus_stats, but the guidance is clear for the primary use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by revealing that traces buffer in memory and only flush to disk upon expiry, and that deleting early loses buffered events. This is critical operational knowledge that annotations do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three sentences, with the purpose stated first and the crucial buffering warning in a compact paragraph. No fluff or repetition of schema fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema fully documents parameters and an output schema exists, the description covers the essential operational caveat (memory buffering, data loss risk) and a clear usage scenario. This is sufficient for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are fully documented in the schema (100% coverage), so the description doesn't need to add parameter details. It does reference the target types ('client, topic or IP') which aligns with target_type, but adds nothing 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 opens with a specific verb phrase 'Start capturing MQTT packets' and scopes it to 'one client, topic or IP', clearly differentiating it from sibling trace tools like emqx_get_trace_log and emqx_delete_trace. It also adds a typical debugging scenario.
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 a concrete use case: 'the device connects but nothing arrives', signaling when to initiate a trace. It also warns against deleting early, guiding the agent to wait for expiry, though it does not explicitly name the companion tools for reading or deleting traces.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explicitly stating the irreversible consequence: 'It cannot be undone — the previous payload is gone unless something republishes it.' It also opens with [DESTRUCTIVE], reinforcing the destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the action, the second provides a use case and consequence. It is front-loaded with a destructive warning and has no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With only one parameter, full schema coverage, and an output schema present, the description covers the purpose, use case, and irreversible nature. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single `topic` parameter with 'Exact topic whose retained message to remove.' The description adds no additional parameter semantics, so the baseline of 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete the retained message for one topic.' It clearly distinguishes this tool from sibling tools like emqx_get_retained and emqx_list_retained by focusing on deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete use case: removing stale Home Assistant discovery entries or ghost device states. It implies when to use it but does not explicitly mention alternatives or when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations readOnlyHint=true, idempotentHint=true, destructiveHint=false, the description discloses the in-memory buffering behavior and the fact that running traces typically return little data. This is non-obvious behavioral context not captured by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences; the first states the core function, the second adds a critical timing caveat. No redundant filler, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values are documented. The tool is simple (name + max_bytes), and the description covers the key behavioral nuance about running traces. Sufficient for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). The description doesn't elaborate on the parameters, so it adds no extra semantic meaning. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and the resource 'what a trace captured', clearly distinguishing from sibling tools like emqx_list_traces (which lists trace metadata) and emqx_create_trace/emqx_delete_trace. It immediately conveys the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes that running traces return little or nothing and that events remain buffered until expiry, implying the tool is most useful after a trace finishes. This gives contextual guidance but doesn't explicitly name alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds beyond annotations by noting the tool lists clients 'known to the broker' (implying both online and offline) and giving pagination strategy. These are useful behavioral details beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and includes only essential examples and tips. Every sentence earns its place—no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and safe read-only annotations, the description covers the essential aspects: what it does, common use cases, and pagination behavior. The optional filters are already documented in the schema, so the description doesn't need to restate them. It is complete for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already well-documented. The description adds value by mapping use cases to parameters ('who is connecting from this IP' relates to ip_address) and offering guidance on page vs limit. This goes beyond the baseline for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'List MQTT clients known to the broker' with specific verbs and resource. It distinguishes itself from sibling tools like emqx_get_client by focusing on listing, and provides example queries that clarify what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by answering common questions like 'which devices are online' and 'is device X connected'. It also offers a specific pagination guideline ('raise page rather than limit'). However, it does not explicitly exclude alternatives like emqx_get_client for single-client lookups, so it falls slightly short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly=false and destructiveHint=true. The description adds valuable behavioral context: operations are limited to create/delete/read, and writes fail if no authenticator exists. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences long, front-loaded with the main purpose, and every sentence earns its place: scope, clarification, prerequisite, and operations. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Combined with detailed schema annotations and output schema, the description covers purpose, use case, prerequisite, and allowed operations. No critical gaps remain for a moderately complex CRUD 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?
All five parameters have full schema descriptions (100% coverage), so baseline is 3. The description adds extra meaning to the operation parameter by explicitly enumerating allowed values (create, delete, read), which the schema description references.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource (MQTT accounts in EMQX's built-in authentication database) and lists the operations (create, delete, read). It also distinguishes these credentials from dashboard logins, preventing confusion and differentiating from sibling tools like emqx_list_authn.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use this tool: for device credentials, not dashboard logins, and includes a necessary prerequisite—create an authenticator first. It does not explicitly name alternative tools or state when not to use it, but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the output is raw Prometheus exposition text and that it is large, which are behavioral traits not captured in the annotations. The annotations already cover read-only/idempotent safety, so the description adds useful size and format context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. It states the resource type and a usage recommendation, every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't detail return format. The annotation covers safety, the schema covers parameters, and the description provides the core purpose and a size warning. For a simple read-only tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single max_bytes parameter, including its purpose and constraints. The tool description does not add any parameter semantics beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning raw Prometheus exposition text, a specific resource, and differentiates it from sibling emqx_broker_stats by recommending that alternative for large outputs. This gives a specific verb and resource, distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Large — prefer emqx_broker_stats,' providing a clear when-to-use alternative. This tells the agent to favor the sibling tool for broker stats while implying this tool is for raw Prometheus text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a critical non-obvious behavior: publishing to a topic with no subscribers succeeds silently, which is not evident from the annotations (readOnlyHint=false, destructiveHint=false). It also implies that a successful publish does not guarantee delivery, adding valuable context beyond the schema. This is a significant behavioral trait that helps the agent take appropriate follow-up actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It consists of two short paragraphs: the first states the purpose, and the second explains the use case and failure behavior. Every sentence earns its place, and the most critical information is front-loaded in the first sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a detailed input schema (100% coverage), an output schema, and clear annotations, the description provides sufficient context. It explains the tool's primary use cases, a key failure mode (silent success), and a diagnostic pointer. This makes the description complete for an agent to select and invoke the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all five parameters with 100% coverage. The description does not add parameter-level semantics beyond what the schema already states. Since the schema carries the full burden for parameter understanding, 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 opens with 'Publish a single MQTT message through the broker', using a specific verb and resource. The word 'single' distinguishes it from the sibling emqx_publish_bulk. It also clarifies the intent with relatable use cases like driving a device or feeding a Home Assistant entity, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: 'This is how you drive a device or feed a Home Assistant MQTT entity.' It also provides troubleshooting guidance ('check emqx_list_subscriptions if nothing reacts'). However, it does not explicitly state when not to use it or mention emqx_publish_bulk as an alternative for multiple messages, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations declare destructiveHint and readOnlyHint, the description adds crucial context that the captured log is deleted and that running traces lose buffered memory events. This goes beyond the structured annotations and alerts the agent to irreversible side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two short sentences deliver the purpose, a warning, and a procedural tip. The [DESTRUCTIVE] label is front-loaded. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter delete operation with an output schema, the description covers the main action, the risk scenario, and a recommended fallback. This is complete and sufficient given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear parameter description ('Trace name to delete'). The tool description does not add further parameter details, but the baseline of 3 is appropriate since the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a trace and its captured log' with a specific verb and resource. It distinguishes itself from sibling tools like emqx_get_trace_log, emqx_create_trace, and emqx_list_traces by focusing on deletion.
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?
Provides explicit guidance: if the trace is still running, buffered events are lost, and recommends calling emqx_get_trace_log first or waiting for natural expiry. This names the alternative tool and gives a clear precondition, exceeding basic usage indications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the destructiveHint annotation by specifying exactly what is destroyed ('Queued and in-flight messages for that session are lost') and that devices with auto-reconnect will return, forcing a fresh connection. This adds meaningful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact: three sentences that each carry weight. It front-loads the [DESTRUCTIVE] warning, then explains the effect and the alternative tool. No unnecessary words are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema and clear annotations, the description fully covers purpose, consequences, and usage context. It even mentions the sibling alternative (emqx_ban), making it self-contained for an agent deciding between tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the clientid parameter fully documented ('Client id to disconnect. Call emqx_list_clients first to get an exact id.'). The description itself does not add parameter details beyond the schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Disconnect an MQTT client and clear its session.' It includes the consequence of losing queued/in-flight messages and contrasts with emqx_ban ('use emqx_ban to keep a client out'), distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'use emqx_ban to keep a client out' clarifies when to use banning instead of kicking. The schema adds a prerequisite: 'Call emqx_list_clients first to get an exact id.' This directly tells the agent how to obtain the required parameter.
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:

[![Woow_emqx_mcp_server MCP server](https://glama.ai/mcp/servers/WOOWTECH/Woow_emqx_mcp_server/badges/card.svg)](https://glama.ai/mcp/servers/WOOWTECH/Woow_emqx_mcp_server)

Score Badge

Copy to your README.md:

[![Woow_emqx_mcp_server MCP server](https://glama.ai/mcp/servers/WOOWTECH/Woow_emqx_mcp_server/badges/score.svg)](https://glama.ai/mcp/servers/WOOWTECH/Woow_emqx_mcp_server)

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/WOOWTECH/Woow_emqx_mcp_server'

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