mcp-superset
Server Quality Checklist
Latest release: v0.3.1
- Disambiguation4/5
The tools mostly have clear, distinct purposes (e.g., dashboard_list vs chart_list vs dataset_list). A few pairs could be confused, such as superset_sqllab_export_csv vs superset_sqllab_results or superset_chart_data vs superset_chart_get_data, but detailed descriptions mitigate ambiguity. Overall, each tool targets a specific object or action, though the sheer quantity makes selection challenging.
Naming Consistency5/5Every tool follows the consistent pattern `superset_<object>_<action>` (e.g., dashboard_create, chart_update, dataset_delete). Exceptions like superset_get_menu or superset_get_current_user still use a verb-oriented convention. No mixed casing or inconsistent verb styles; the prefix `superset_` unifies the entire set.
Tool Count1/5With 137 tools, this is far beyond the typical well-scoped server and exceeds even the 50+ threshold for an extreme mismatch. While Superset is a complex platform, exposing this many tools burdens the agent with excessive choice and likely includes many rarely-used operations. The count is inappropriate for efficient discovery and selection.
Completeness5/5The tool surface covers comprehensive CRUD and lifecycle operations for all major Superset entities: dashboards, charts, databases, datasets, users, roles, RLS rules, tags, reports, annotations, and groups. It also includes import/export, bulk operations, permissions auditing, and SQL lab utilities. No obvious gaps prevent common workflows; the set is remarkably thorough.
Average 4.2/5 across 137 of 137 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- 6 of 6 community issues answered or closed in the last 6 months
- 6 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It does not mention the implication of renaming (e.g., impact on references, uniqueness constraints, permissions required, reversibility). The tool appears to be a mutation, but no side effects or safety information is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and free of unnecessary words. The first line immediately states the action, and the argument list is clear. Every sentence earns its place, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description is incomplete for a mutation tool with no annotations. It lacks information about required permissions, side effects, error conditions, or relationship to other role management tools. The agent cannot fully assess the impact of invoking this tool without additional external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds brief definitions for the parameters ('ID of the role to rename', 'New role name'), but these essentially restate the parameter names. With 0% schema description coverage, the description should compensate with richer semantics such as constraints, format, or uniqueness requirements, which it does not. The value added over raw schema is minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action with a specific verb ('Rename') and resource ('role'), distinguishing it from sibling tools like role create, delete, or get. It is unambiguous and 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 Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not mention when to use this tool versus other role-related tools, nor any prerequisites, permissions, or context. The agent is left without direction on appropriate invocation scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose side effects and behavior. It fails to mention that deletion is permanent, whether confirmation is required to execute, or any safety caveats. The claim that confirm_delete is 'REQUIRED' contradicts the input schema, which lists it as optional with a default of false, misleading the agent about the tool's expected usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, using a standard docstring format with an Args section that is easy to scan. It earns points for brevity, but the misleading '(REQUIRED)' for confirm_delete and the lack of elaboration prevent a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the description is too thin. It does not mention the return value, error conditions, or the semantic effect of confirm_delete (which is central to the operation). The output schema exists but is not referenced, so the agent has to rely on the description for context, which is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description lists each parameter with a brief label ('Annotation layer ID', 'Annotation ID to delete', 'Deletion confirmation'), but only restates the schema names and types without adding meaningful context. It incorrectly marks confirm_delete as required, misrepresenting its role, and gives no indication that it must be set to true to proceed. Schema coverage is 0%, so the description was expected to compensate, but it largely does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an annotation from a layer' with a specific verb and resource. It differentiates from sibling tools like annotation_create, annotation_update, and annotation_get by explicitly indicating deletion, so an agent can easily identify its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a basic 'delete' context but gives no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The presence of sibling annotation tools implies a delete scenario, but there is no direct 'use this when...' or comparison, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It states the mutation ('Remove users') and the partial-scope guarantee ('without removing the rest'), but does not mention permissions, error handling for nonexistent users or groups, idempotence, or other side effects. This is insufficient for a write operation with no safety annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: the first sentence states the core function, and the Args block cleanly lists parameters. Every sentence adds value, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter mutation tool with an output schema, the description gives the essential intent and partial-scope behavior. However, it omits important context such as prerequisite conditions, failure semantics, and authentication/authorization requirements. It is minimally adequate but leaves clear gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args block adds minimal but useful semantics: user_ids is described as 'List of user IDs to remove from the group,' which goes beyond the raw schema. However, group_id is just restated as 'Group ID' with no additional context, and schema coverage is essentially zero, so the description only partially compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific action: 'Remove users from a group without removing the rest.' This clearly identifies the verb, resource, and scope, and distinguishes it from siblings like group_remove_roles or group_add_users by focusing on users rather than roles and by emphasizing partial removal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit when-to-use guidance or mention of alternatives. The phrase 'without removing the rest' implies targeted partial removal, but there is no direct comparison to related tools like group_add_users or group_remove_roles, and no conditions for when this tool should or should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Get an annotation by ID'—a direct restatement of the tool name—and adds no behavioral context such as error handling, permissions, or the need for both IDs. There is no discussion of what happens if the annotation is not found or whether the operation is read-only beyond the verb 'get'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: one sentence for the purpose and a clean args list with brief definitions. Every word earns its place, and there is no fluff or unnecessary repetition. The structure is easy to scan for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple getter with an existing output schema, so return values are covered elsewhere. The description adequately explains the two required parameters and the purpose. However, it lacks broader context about when to use the tool, what the output represents, or any prerequisites beyond having the IDs. It is minimally complete but leaves room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides one-line explanations for both parameters, which the input schema lacks entirely (schema description coverage is 0%). It clarifies that annotation_layer_id is the layer ID and annotation_id comes from annotation_list, offering useful context for obtaining valid values. While terse, this meaningfully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get an annotation by ID') and identifies the resource. It implicitly distinguishes from sibling tools like annotation_list (which lists annotations) and annotation_create/update/delete, though it does not explicitly contrast with them. The note 'from annotation_list' on the annotation_id parameter suggests a workflow, adding slight differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides only implied usage context: to get a single annotation, you need an annotation ID (obtained from annotation_list) and a layer ID. It does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The 'from annotation_list' hint gives some workflow guidance, but overall the usage guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It conveys a read-only operation ('Get') but does not disclose additional behaviors such as error conditions, permission requirements, or response size. The return format is presumably covered by the output schema, but the description itself provides minimal context beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences for purpose/usage and a minimal Args block. It front-loads the core function, avoids redundancy, and every sentence contributes value. Well-structured for quick agent scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with a single required parameter and an output schema exists, which reduces the burden on the description. Purpose, use case, and parameter are all covered succinctly. However, it could benefit from a brief mention of the output structure or typical use cases relative to dashboard-related siblings, but overall it is complete enough for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The Args section only restates the parameter name ('dashboard_id: Dashboard ID') without adding meaningful guidance on source, format, or usage. This is not enough to compensate for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pattern ('Get the list of all datasets used by a dashboard's charts'), making the tool's purpose unambiguous. It clearly distinguishes itself from broader tools like superset_dashboard_get or superset_dataset_list, though it does not explicitly reference sibling tool names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a clear use case ('Useful for understanding the dashboard's dependencies on data sources'), which implies when to use the tool. However, it lacks explicit exclusions or mentions of alternative tools like superset_dashboard_charts, so the guidance is somewhat implicit rather than fully articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It discloses the direct consequence ('can no longer be embedded via iframe'), which adds useful context, but it omits other behavioral aspects such as reversibility, required permissions, or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded. The first sentence states the action, the second clarifies the effect, and the Args section is minimal and useful. Every sentence earns its place without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description is adequate: it covers the purpose and outcome. However, it lacks any information about error handling, idempotency (e.g., what happens if embedding is already disabled), or prerequisites. Since an output schema exists, omitting return values is acceptable, but behavioral edge cases are still missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description only restates the parameter name as 'Dashboard ID', which adds little beyond the property name 'dashboard_id'. It does not clarify the meaning or provide any additional semantic context, so the description fails to compensate for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific action ('Disable dashboard embedding') with a resource (dashboard embedded mode) and explains the tangible consequence ('can no longer be embedded via iframe'). This clearly distinguishes it from sibling tools like embedded_get or embedded_set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool instead of alternatives, nor any mention of related operations like set or get. The purpose statement implies usage, but the description does not provide contextual 'when' or 'when not to' advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It usefully notes that users are not deleted but lose group-assigned roles, yet it omits permanence, permission requirements, and whether confirm_delete must be true. It also misstates confirm_delete as 'REQUIRED' while the schema marks it optional with a default of false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences plus a minimal args list; every sentence earns its place. The main action is front-loaded and the side effect is immediately stated without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core behavior and side effect are present, and an output schema exists, but the description lacks usage context and irreversibility/permission details. The confirm_delete/schema mismatch leaves a completeness gap for an unannotated destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It identifies group_id as 'ID of the group to delete' and confirm_delete as 'Deletion confirmation,' but the latter adds little beyond the parameter name and does not clarify that it must be true to proceed. The 'REQUIRED' note contradicts the schema's optional/default false declaration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a user group,' which clearly states the verb and resource. It also distinguishes itself from sibling tools like user_delete or role_delete by specifying the target is a user group, and adds a key caveat that users are not deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does 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. It does not mention prerequisites, required permissions, or situations where group deletion is preferred over group_update or group_remove_users.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the return value (chart IDs and names) and scope ('all charts'), but does not mention error handling, permission requirements, or pagination. This 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three short sentences that state purpose, output, and argument. It is front-loaded and contains no filler or redundant content, every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool with an output schema, the description is reasonably complete. It specifies what the tool does, what it returns, and identifies the parameter. The absence of alternative tool references is a minor gap, but not critical for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's 'Args' section merely repeats the parameter name, providing no additional meaning beyond the schema. With schema description coverage at 0%, the description fails to compensate, offering no context about where to find the dashboard_id or any constraints beyond it being an integer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and clearly identifies the resource: 'the list of all charts placed on a dashboard.' This distinguishes it from sibling tools like superset_chart_list (which lists all charts) and superset_dashboard_get (which retrieves dashboard details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a use case ('Useful for analyzing dashboard contents') but does not explicitly state when to choose this tool over alternatives or mention exclusions. It could have indicated to use superset_dashboard_get for dashboard-level metadata or superset_chart_list for a global list of charts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the action is an enable/configure operation and discloses important behavior for allowed_domains ('Empty list = all domains'), but it does not describe whether existing embed settings are overwritten, the effect of null vs empty list, or any security considerations for allowing all domains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a front-loaded statement of purpose followed by a clear Args section. Each sentence contributes useful information, and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description leaves a significant ambiguity: allowed_domains has a default of null in the schema, but the description only explains empty list behavior. It is unclear whether null means no domains, all domains, or leaves current settings unchanged. It also does not mention whether calling this tool overwrites existing embed configuration, which is important for a setter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides meaningful detail for allowed_domains (list of domains, examples, empty list behavior), but dashboard_id is only described as 'Dashboard ID,' which adds no meaning beyond the parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Enable dashboard embedding (embedded mode) and configure allowed domains.' This is a specific verb+resource combination and is distinct from the sibling tools (e.g., embedded_get, embedded_delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the consequence of using the tool ('Once enabled, the dashboard can be embedded via iframe on the specified domains') which implies the use case, but it does not explicitly say when to use this tool versus alternatives, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden. It adds useful detail by stating that it 'Parses json_metadata' and returns a specific set of filter properties. However, it does not explicitly confirm the operation is side-effect-free or mention permission requirements, error handling, or empty-result behavior. The verb 'Get' implies non-mutation, but the disclosure is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: an intro sentence, a clear list of returned fields, and a short Args section. Every sentence earns its place, with no redundant or verbose content. It front-loads the primary purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only listing tool with an existing output schema, the description is largely complete. It explains the key behavioral aspect (parsing json_metadata) and enumerates the returned configuration fields. Minor omissions such as permission requirements or error scenarios are acceptable given the low complexity and presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, dashboard_id, receives a minimal explanation in the Args section: 'Dashboard ID.' This adds little beyond the parameter name and integer type in the schema. Since schema description coverage is 0%, the description should compensate with richer context (e.g., 'ID of the dashboard whose native filters to retrieve'), but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Get a list of native filters on a dashboard in a readable format.' It clearly distinguishes from sibling filter mutation tools (add/update/delete/reset) by enumerating the returned filter configuration fields, making the read-only listing intent unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. It does not state 'use this to inspect filters before updating' or mention any exclusions. The read-only nature is implied but not framed as a choice among sibling operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the URI excludes the password, which is a meaningful behavioral trait for privacy. However, it does not explicitly state that this is a read-only operation or mention any auth/rate-limit considerations, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and well-structured, with a single sentence front-loading the main purpose followed by a clear Args block. Every word earns its place, making it easy to scan and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool (one parameter, output schema exists), the description covers the core purpose and the critical security note about password omission. It does not explain what 'parameters' means or any operational details, but for this simple read-like tool, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description's 'Args: database_id: Database connection ID' provides basic semantics. It clarifies that the parameter is an ID, but it largely restates the parameter name without adding deeper context, offering only marginal compensation for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get connection information (URI without password, parameters)' with a specific verb and resource. It is not a tautology and adds a key detail about password exclusion. However, it does not explicitly distinguish from siblings like superset_database_get, which might also return connection details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating what the tool does, but provides no explicit guidance on when to use it vs alternatives or any exclusions. It lacks context about prerequisites or when to prefer other database-related tools, so only implicit usage is conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the delivery schedule will be stopped, which is useful. However, it does not state whether deletion is irreversible, what permissions are needed, or what happens if confirm_delete is false. Given no annotations, more disclosure would be expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences plus an args list. Every sentence adds value; the structure is clear and front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but the description omits critical behavioral details such as irreversibility, the exact semantics of confirm_delete (must be true?), and the return value. The output schema may cover the return, but the confirm_delete ambiguity is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains report_id as 'Report ID to delete' and confirm_delete as 'Deletion confirmation (REQUIRED)', adding meaning beyond the schema's bare types. However, the schema marks confirm_delete as optional with a default of false, so the 'REQUIRED' label is ambiguous and could mislead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it deletes a report/alert, and specifies the consequence that the delivery schedule is stopped. Differentiates from report_create/update/get/list by naming the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use vs alternatives, but the description implies its purpose by naming 'Delete' and the effect. The confirm_delete argument is marked REQUIRED, giving some usage guidance, though no exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states the core behavior (pretty print with indentation) but does not disclose side effects or safety. Since no annotations are present, the description carries the full burden. However, the action is clearly a pure transformation, so a basic level of transparency is met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, and an args list. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter formatter with an output schema, the description is mostly complete. It could mention that the query is not executed, but that's inferable from the name and sibling context. Minor gaps in usage guidance exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter 'sql' with no description. The description adds 'SQL query to format,' which clarifies the expected input, though it largely mirrors the parameter name. It does not specify constraints like valid SQL syntax or length limits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool formats a SQL query with pretty print indentation. This specific verb+resource combination distinguishes it from siblings like superset_sqllab_execute, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, whether the SQL is executed, or any exclusions. An agent is left to infer that it's a formatting utility.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior. It mentions the primary action (warm up cache) but does not explain side effects, whether the operation is synchronous, any permission requirements, or what the return value indicates. This leaves significant behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with the core action, then provides a brief usage note, followed by parameter documentation. Every sentence adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool, the description covers purpose and parameters adequately. However, the absence of annotations and any mention of execution behavior (e.g., synchronous vs. asynchronous, caching semantics, or return value) leaves gaps. The output schema exists but is not described, so the description is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by documenting both parameters. It defines chart_id as 'ID of the chart to warm up' and dashboard_id as 'Dashboard ID for filter context (optional)', which adds some meaning, especially for dashboard_id. However, the explanations are minimal and do not elaborate on how dashboard_id affects the cache warmup process.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Warm up the cache for a chart' with a specific verb and resource. It also explains the motivation ('speeding up loading of frequently used charts'), which distinguishes it from sibling tools like superset_chart_get or superset_chart_data that retrieve data rather than pre-warm cache.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use the tool ('Useful for speeding up loading of frequently used charts'), but it does not explicitly mention when not to use it or name alternatives. This gives clear usage context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It explains pagination semantics, including that get_all overrides page/page_size and automatically paginates. It also scopes activity to the current user and lists activity types (views, edits). However, it does not mention authentication requirements, whether the operation is read-only (though implied), or any other side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct and well-structured. It starts with a clear one-sentence purpose, then lists each parameter with its behavior. There is no wasted wording, and all sentences contribute to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the presence of an output schema, the description is largely complete. It explains all parameters and their interactions. Minor gaps include not specifying whether the activity list can include other types beyond views and edits, and not mentioning any date filters or sorting behavior. Still, it provides enough 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.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully carries parameter semantics. It explains page starts at 0, page_size max is 100, and get_all fetches all records with automatic pagination, ignoring page/page_size. This adds meaningful usage guidance beyond the bare schema, which only shows defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets recent activity of the current user, specifically views and edits. It uses a specific verb and resource, making the purpose understandable. However, it does not explicitly distinguish itself from sibling tools like superset_log_list or superset_get_current_user, though the 'current user activity' scoping helps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or preferred contexts. For example, there is no note that this should be used over superset_log_list for user-centric activity tracking. The only usage-related details are parameter explanations, not scenario-based guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly states the action is 'Create' which implies mutation, but it does not disclose permission requirements, behavior on duplicates, or what happens with the optional descr. It adds only the layer-container context, not deeper behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short lines of prose plus a compact Args list. It front-loads the action and every sentence contributes context or parameter meaning, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter create operation with an output schema, the description is mostly adequate. It explains what a layer is and defines both parameters. It doesn't discuss error conditions or permissions, but these are less critical given the tool's simplicity and presence of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only names and types with no descriptions (0% coverage). The Args section supplies one-line semantics for both parameters, clarifying 'descr' as a description and marking it optional. This meets the minimum but doesn't add details like allowed formats or defaults beyond the schema's default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new annotation layer,' naming the exact verb and resource. It also explains that a layer is a container for annotations, distinguishing this from related tools like annotation_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context by explaining a layer is a container for annotations for time-series charts, implying layers are created before annotations. However, it does not explicitly state when to use this tool versus alternatives such as superset_annotation_create or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the primary behavioral outcome (visibility to users with permissions), but does not discuss caller permissions required, reversibility (via unpublish), or any side effects. It adds some context beyond the name but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence plus a structured Args section. Every word earns its place—no fluff, clear structure. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter mutation, the description covers the core action but omits important context like required permissions for the caller, behavior on nonexistent dashboard, or relationship to 'unpublish.' The tool is straightforward, so a 3 is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It simply restates 'dashboard_id: Dashboard ID' without adding meaning such as where to find the ID, format constraints, or that it belongs to an existing dashboard. This is minimal and does little beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Publish') and resource ('dashboard'), and clarifies the effect with the parenthetical 'make it visible to users with appropriate permissions.' This clearly distinguishes it from siblings like superset_dashboard_unpublish and superset_dashboard_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 want to make a dashboard visible to users) but does not explicitly mention alternatives or exclusions. It provides clear context without naming sibling tools or stating when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait—preserving other roles—but does not mention permissions, error conditions (e.g., nonexistent group or role), or side effects beyond the direct removal. This is adequate for a basic understanding but leaves significant gaps for a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise: one main sentence plus a brief Args list. Every sentence earns its place, with no redundant information. The structure front-loads the purpose and then cleanly lists parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple signature (2 params, no nesting) and an output schema exists, so return handling is covered elsewhere. However, the description lacks any prerequisites, side effects, or error behavior, which is a notable gap for a mutation tool. It is minimally complete for a basic select-remove operation but not rich enough for robust decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists 'group_id: Group ID' and 'role_ids: List of role IDs to remove', which essentially restates the schema types and names. The only added semantic is 'to remove' for role_ids, which is minimal. It does not clarify requirements like whether roles must already be assigned or behavior for invalid IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove roles from a group' and specifies the scope 'without removing the rest', distinguishing it from a full role replacement or clearing. This verb+resource+scope structure makes the purpose unambiguous and differentiates it from sibling tools like superset_group_add_roles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without removing the rest' implies the intended use case (selective role removal) and sets a clear context. However, it does not explicitly mention alternatives or exclusions, such as when to use group_update or bulk_user_role_remove instead. The guidance is implicit but clear enough for a simple operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Get detailed information'—implying a read operation—but does not disclose potential side effects, permissions required, error behavior, or response characteristics. For a tool with zero annotation support, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only two sentences (or lines) to convey the tool's purpose and parameter hint. Every word contributes useful information, with no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema present, the description covers the essential purpose and parameter. It lacks a bit of surrounding context, such as any preconditions beyond having an ID, or what to do if the rule doesn't exist, but these are minor gaps given the tool's simplicity and the existence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only describes rls_id as an integer, but the description enriches it with the note '(from rls_list)', clarifying the ID's source and how to obtain it. With only one parameter and 0% schema coverage, this added context is valuable and makes the parameter easier to use correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get detailed information about an RLS rule by ID.' This is a specific verb+resource+scope, and it distinctly stands out from sibling tools like superset_rls_list, superset_rls_create, etc., as the fetch-one variant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at usage by specifying 'rls_id: RLS rule ID (from rls_list)', which tells the agent where to obtain the ID. However, it does not explicitly state when to use this tool vs. listing rules or other RLS operations, leaving the primary usage context implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly discloses the destructive behavior: 'Deletes all current filters and creates new ones from the provided list.' and repeats this with 'CRITICAL: all current filters will be DELETED.' It also explains automatic population of fields like chartsInScope and defaultDataMask. However, it does not cover potential side effects beyond filters, such as permission implications or reversal details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise but includes a mix of prose, a warning, and an args section with a JSON example. The structure is mostly effective, though the placement of 'confirm_reset' between 'filters_json' and the JSON block causes a minor readability hiccup. Every sentence contributes to understanding the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and 0% schema coverage, the description covers the essential aspects: what it does, the parameters, and the filter format. It does not describe the return value, but since an output schema exists, that is acceptable. The main gap is the confirm_reset contradiction, which slightly undermines completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description is critical. It adds meaning for each parameter, especially filters_json with a detailed JSON example and allowed types. However, it states that confirm_reset is 'REQUIRED' while the schema lists it as optional with a default of false, creating a contradiction. This misleading instruction reduces the value of otherwise strong parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Recreate ALL native filters on a dashboard with correct defaults.' It uses a specific verb ('recreate'), defines the resource ('native filters on a dashboard'), and explicitly contrasts with siblings by emphasizing 'ALL' filters. This distinguishes it from individual filter operations like filter_add or filter_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you need to replace all filters with a new set. It does not explicitly mention when not to use it or suggest alternatives, such as using filter_delete for individual removals or filter_update for modifying existing filters. The destructive nature is clear, but a direct 'use this instead of...' comparison is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It clearly discloses critical side effects: 'breaks ALL datasets, charts, and dashboards using this DB' and notes associated datasets become broken. This goes beyond the basic delete action and is essential for safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the purpose, followed by a critical warning and parameter list. It slightly repeats the cascading breakage information but remains overall efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, side effects, and parameters adequately. An output schema exists, so return values need not be explained. The main gap is missing details on behavior when confirm_delete is omitted or false, but the critical warning and parameter list provide enough context for a destructive operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains both parameters: database_id as the connection ID and confirm_delete as deletion confirmation. However, calling confirm_delete 'REQUIRED' conflicts with the schema, where it is optional with a default of false. This adds meaning but also introduces ambiguity about whether it must be provided or set to true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a database connection' with a specific verb and resource, distinguishing it from sibling tools like database_update or dataset_delete. The scope is precise 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use is for deleting a database connection but does not explicitly state when to use this tool over alternatives or provide exclusion criteria. No alternatives are mentioned, and the cascading warning serves as precaution rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It discloses the action (rescan columns and types) and the return type (JSON string). However, it does not mention side effects, permission requirements, or potential failure modes. This is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-sentence purpose, a usage note, and a simple args/returns section. Every sentence adds useful information without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a single integer parameter and an output schema, the description covers the purpose, when to use it, and the return type. It lacks details on errors or prerequisites, but it is sufficiently complete for the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only says 'dataset_id: Dataset ID,' which adds no meaning beyond the parameter name and schema type. Since there is only one parameter, the gap is small, but the description does not compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Refresh the dataset schema from the source (rescan columns and types).' This uses a specific verb and resource, and it is distinct from sibling tools like superset_dataset_get or superset_dataset_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: 'Useful after ALTER TABLE or any structural change to the underlying table.' This tells the agent when to invoke this tool, though it does not explicitly mention alternatives or exclusions. The context is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It merely restates the action ('Stop a running asynchronous query') without detailing side effects, irreversibility, idempotency, or error behaviors. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with two sentences and an Args section. It is front-loaded with the purpose and structured clearly. Every word earns its place without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter, and the description covers purpose and parameter semantics. However, it lacks behavioral details like what happens upon success or failure, and whether stopping is reversible. Given the output schema exists, return values are covered, but the description is still minimal for a destructive action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It adds meaningful context by explaining that query_id is the client_id from sqllab_execute result, clarifying its origin and format. This goes beyond the schema's bare string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Stop') and resource ('running asynchronous query'), clearly distinguishing it from sibling tools like query_get or query_list. It also specifies the query state, making the action 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by stating the query_id comes from sqllab_execute result, indicating this is for stopping queries initiated by that tool. It provides clear context but does not explicitly list alternative tools or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It does describe pagination behavior (page, page_size, get_all) and clarifies that reports and alerts are different types. However, it does not explicitly state that the operation is read-only or safe, and it does not mention any potential side effects, permissions, or rate limits. The verb 'List' implies a read operation, but this is not stated explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a clear one-line purpose, two short explanatory sentences about reports vs alerts, and an organized Args section with examples. Every sentence adds value, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly explains the purpose, the resource types, and all parameters. The output schema exists, so return values are covered. It falls slightly short in not providing explicit use-case guidance (e.g., when to use this vs superset_report_get), but for a list operation with such detailed parameter documentation, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides extensive parameter details that the input schema lacks (schema coverage is 0%). It explains the meaning of page (starting from 0), page_size (max 100), get_all (ignores page/page_size), and gives concrete RISON filter examples with syntax for filtering by name, type, and active status. This far exceeds what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List Superset reports and alerts.' It also distinguishes between reports and alerts, which adds specificity. This differentiates it from sibling tools like superset_report_get (which retrieves a single report) and other list tools for different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as superset_report_get or superset_report_create. It does not mention exclusions or alternative tools. Usage is only implied by the verb 'List' and the resource type, but no explicit context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure but only lists parameters and the action 'Create'. It does not mention permissions, return behavior, uniqueness constraints, validation, or side effects beyond the creation itself, similar to the 'Update shared drive settings' middle example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise one-liner followed by a compact, well-formatted args list. Every element provides useful information with no redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no annotations, the description fully covers all parameters and their purpose, which is sufficient for a simple create operation. It omits return values, but since an output schema exists, that is acceptable. It could add more context about prerequisites or error cases, but the current coverage is solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description provides human-readable explanations for all five parameters, including a source hint for db_id and an example for schema ('public'). This adds significant meaning beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and resource ('saved SQL query') with its purpose ('for reuse'), clearly distinguishing it from saved_query_list/update/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for saving reusable SQL queries, and the arg details note that db_id comes from superset_database_list, providing a cross-tool reference. However, it does not explicitly state when to use this over alternatives like superset_sqllab_execute or saved_query_update, so guidance remains implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the partial-update behavior ('Pass only the fields to change') but does not mention required permissions, side effects, or how null values affect fields. The output schema's existence reduces the need to describe return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with 'Update an annotation layer.' The Args list is structured and directly maps to the schema. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with three parameters and an output schema, the description is largely complete. It covers the purpose, parameter semantics, and partial-update behavior. It could improve by explicitly contrasting with annotation_layer_create or explaining error scenarios, but it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It defines each parameter: annotation_layer_id as the layer ID, name as the new name, and descr as the new description. It also clarifies that only fields to change need to be passed. It lacks details on null semantics or constraints, but covers the essentials.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description says 'Update an annotation layer' – a specific verb and resource. It clearly distinguishes itself from siblings like annotation_layer_create, annotation_layer_get, and annotation_layer_delete by focusing on updating an existing layer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Pass only the fields to change' implies partial-update semantics and provides usage context. However, it does not explicitly state when to use this tool instead of create/delete or mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden. It reveals that the tool performs a partial update, but it does not disclose potential side effects, error conditions, or required permissions. The mutation nature is implied by 'update', but deeper behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one opening sentence and a clean argument list. Every line is informative and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with six parameters and an output schema, the description provides all necessary invocation details: which IDs are required, which fields can be changed, and datetime formats. It does not explain broader concepts like what an annotation is, but the Superset context and sibling tools make that unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It lists all six parameters with brief explanations and adds ISO format details for start_dttm and end_dttm. However, short_descr and long_descr descriptions are largely tautological, and the distinction between them is not deeply elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Update an annotation' with a specific verb and resource, clearly distinguishing it from sibling tools like annotation_create, annotation_get, and annotation_delete. The action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Pass only the fields to change' provides clear context for partial updates, which is essential for this tool. It does not explicitly mention alternatives or when not to use, but the update purpose is obvious from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the key side effect (removal from all dashboards) and emphasizes that confirm_delete is required, revealing a safety mechanism. However, it does not mention irreversibility, permission requirements, or what happens if confirm_delete is false, leaving some behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one purpose sentence and a bullet-like list of parameters. Every element serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description provides the necessary facts: what is deleted, the impact on dashboards, and the need for confirmation. The presence of an output schema reduces the need to describe return values. However, the ambiguous treatment of confirm_delete (schema says optional, description says required) could confuse an agent, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description is the sole source. It defines chart_id as the ID of the chart and confirm_delete as a required confirmation, which adds meaning. It doesn't specify that confirm_delete must be true to proceed, but the 'REQUIRED' label provides essential context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a chart by ID' and explicitly notes the side effect of removal from all dashboards, distinguishing it from other chart operations like update or get. This is a specific verb+resource with clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like superset_dashboard_delete or superset_chart_update. The description merely states the action without any conditions, prerequisites, or situations where this tool should or shouldn't be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context: the operation is non-creating (a test only) and the URI must be reachable from the Superset server. It does not mention what happens on failure or whether the operation has side effects, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief, with a clear initial sentence followed by an IMPORTANT note and a structured Args list. Every sentence adds information, and the formatting makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the description covers its core purpose, the key prerequisite, and all three arguments. An output schema exists, so return values need not be described. It lacks details like error handling or permissions, but for a non-destructive test operation, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It clarifies that database_name is only a connection name shown in error messages (not the actual database), and extra is a JSON string for additional settings. The sqlalchemy_uri explanation is largely a restatement of the parameter name, but the overall param documentation is minimally helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Test' and explicitly states 'without creating it', which clearly distinguishes it from superset_database_create and superset_database_update. It identifies the resource (database connection) and the action (test).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without creating it' implies that this tool should be used to validate a connection before committing to creation, contrasting with superset_database_create. It also highlights an important prerequisite ('URI must be reachable from the Superset server'). However, it does not explicitly name alternative tools or state when not to use it beyond the creation contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does state that no connection is created, which is a key side effect, but it omits details on what validation entails, whether any network calls are made, how errors are returned, or whether credentials are actually checked. This leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and structured with a one-sentence summary followed by an Args block. Each line provides essential detail for the three parameters, with no filler or redundancy. The formatting is clear and scannable, though slightly longer than minimal due to the example dictionary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description sufficiently covers the input parameters and the primary behavior. The main missing piece is a more explicit explanation of validation semantics and limitations, but for a parameter-validation tool, the essential context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no property descriptions (0% coverage), but the description thoroughly explains each parameter: engine provides examples ('postgresql', 'mysql', etc.), parameters includes a sample dictionary structure, and configuration_method lists its default and accepted values. This fully compensates for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description's first sentence 'Validate database connection parameters without creating a connection' clearly states the action (validate), the object (database connection parameters), and the key qualifier that distinguishes it from siblings like superset_database_test_connection. This makes the tool's purpose explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool over alternatives such as superset_database_test_connection. The qualifier 'without creating a connection' implies its niche, but there is no direct guidance on choosing this tool vs. testing a connection, leading to only implicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It clearly states that 'Get' is a read operation and describes the return type as a 'JSON string with related charts and dashboards.' However, it does not discuss potential errors, permissions, or any side effects, leaving some gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with separate sections for purpose, usage, args, and returns. Every sentence adds useful information without padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter lookup tool, the description covers the essential aspects: purpose, when to use, the input parameter, and the return type. An output schema is noted, so detailed return structure is not required. It is missing some edge-case behavior (e.g., empty results) but is reasonably complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter, dataset_id, with no descriptions. The description adds a 'Dataset ID' label for the argument, which slightly clarifies the parameter but does not go beyond what the parameter name already implies. Since schema coverage is 0%, the description partially compensates but not richly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Get objects related to a dataset') and explicitly narrows the scope to 'charts and dashboards'. This distinguishes it from sibling tools like superset_database_related_objects and superset_dashboard_datasets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit use case: 'Useful before deleting a dataset to understand the impact.' This is clear context for when to use the tool, 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It discloses the return format (JSON with IDs and names) and clarifies that the current user is the mcp_service. However, it does not explicitly state that this is a read-only operation, nor does it mention potential errors, authentication requirements, or behavior when no roles exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, consisting of one clear sentence plus a brief return note. Every word contributes to understanding, with no redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter getter with an output schema, the description adequately covers purpose and return shape. It does not discuss edge cases like empty role lists or required permissions, but these are not critical given the tool's simplicity and the presence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already covers everything. With 100% schema description coverage and no params, the description adds no parameter-specific semantics, which is appropriate. The baseline for zero params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get the list of roles for the current user', specifying the verb, resource, and scope. Distinguishes from siblings like superset_role_list (all roles) and superset_get_current_user (current user info) by focusing on roles for the current user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and description (to retrieve current user's roles), but no explicit guidance is given about when to prefer this over alternatives like superset_role_list or superset_get_current_user. No exclusions or when-not-to-use conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing side effects. It explicitly states the key behavior 'without removing existing ones,' but does not mention idempotency, duplicate handling, required permissions, or failure behavior. It adds some context but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with one sentence stating purpose and a clean Args block for parameters. No redundant information; it is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with two parameters, the description covers the action and parameters. It lacks information about edge cases (e.g., duplicate role IDs, group existence) and auth requirements, but the presence of an output schema and the simplicity of the operation make this acceptable. It does not explain return values but those are likely in the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides an Args section that explains both parameters: 'group_id: Group ID' and 'role_ids: List of role IDs to add.' This adds meaning beyond the raw types (integer and array of integers), clarifying that role_ids are the roles to be added. It does not specify constraints like non-empty or uniqueness, but it is sufficient for basic usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action 'Add roles to a group' and immediately clarifies the non-destructive behavior 'without removing existing ones.' This clearly distinguishes it from sibling tools like superset_group_remove_roles and conveys the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when adding roles while preserving existing assignments) but provides no explicit alternates or when-not-to-use guidance. There is no reference to related tools or conditions such as 'use this instead of group update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It describes a read operation ('Retrieve') but does not explicitly state that it has no side effects, nor does it mention error handling, permissions, or rate limits. The lack of any warning or safety information is a gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence for purpose and one for the parameter. Every word earns its place, and the structure is front-loaded with the action, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, output schema exists), the description covers the essential purpose and parameter meaning. It could add a note about when to use this instead of other query-related tools, but overall it is sufficiently complete for a straightforward retrieval operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful context to the single parameter query_id by specifying its type ('integer') and its provenance ('from query_list result'). Since the schema provides only the type with no description, this compensates well for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and identifies both the resource ('detailed information about a query') and the lookup key ('by ID'). This clearly distinguishes the tool from sibling tools like superset_query_list (which lists queries) and superset_query_stop (which stops a query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The mention of 'integer from query_list result' implies a workflow where query_list is used first to obtain the ID, then query_get retrieves details. This gives clear contextual guidance on when to use the tool, though it doesn't explicitly state 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?
The description discloses that confirm_delete is a required confirmation, indicating the destructive nature of the operation. This adds behavioral context beyond the schema, which marks it optional with a default of false. However, it does not explicitly state that deletion is irreversible or describe any additional 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a one-line purpose followed by a brief Args list. It is well-structured and front-loaded, with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two parameters, the description covers the core functionality and the confirmation mechanism. However, it omits details about return values, permissions, and irreversibility, relying on the output schema and common sense. Given the lack of annotations, a bit more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are explained in the description: saved_query_id identifies the target, and confirm_delete is the deletion confirmation. This compensates for the 0% schema description coverage, though the description could clarify that confirm_delete should be set to true to actually delete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Delete a saved query', using a specific verb and resource. This clearly differentiates it from sibling tools like superset_saved_query_list, get, create, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided beyond the action itself. The description does not mention when to use this tool versus alternatives, nor any prerequisites or contraindications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states what will be retrieved and lists the specific fields (SQL text, schema, description), which is useful. However, it does not disclose error behavior (e.g., if ID not found), authorization requirements, or any side effects. For a read-only getter, this is a moderate 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: a one-line summary with the core purpose and return fields, followed by a compact Args section. 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.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter getter with an output schema, the description covers the essential information: what the tool does, what it returns, and how to obtain the required ID. It omits error handling details, but that is a minor gap given the low complexity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It defines saved_query_id as 'Saved query ID (from saved_query_list)', adding provenance context beyond the raw type 'integer' in the schema. This is helpful but minimal; no additional constraints or examples are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource structure: 'Retrieve a saved query by ID', which clearly distinguishes it from siblings like superset_saved_query_list (list) and superset_saved_query_delete (delete). It also enumerates the key return fields (SQL text, schema, description), adding precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by instructing that the saved_query_id should come from saved_query_list, establishing a prerequisite. It does not explicitly mention alternatives or when not to use, but for a simple get-by-ID tool, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses pagination semantics (page starts at 0, page_size max 100, get_all ignores page/page_size) and provides filter examples. However, with no annotations provided, it only implies read-only behavior via 'Retrieve' and does not mention authentication, ownership scope, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized, opening with a one-line purpose statement followed by clearly labeled argument bullet points. Examples are embedded directly without fluff, earning their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema (so return values need not be described), the description covers all parameters and their interactions (pagination vs get_all), provides filter syntax, and is sufficient for a list operation of moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by explaining each parameter: page, page_size, q (with concrete RISON examples for label and database filters), and get_all (automatic pagination). This adds substantial meaning beyond the schema's bare types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and resource ('list of saved SQL queries'), clearly distinguishing it from siblings like superset_query_list (executed queries) and superset_saved_query_get (single query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as superset_saved_query_get or superset_query_list. The description focuses on parameters but does not provide context or exclusions for choosing this list endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Update a saved query' without mentioning required permissions, side effects, error conditions, or whether the update is partial versus full replacement. The 'Pass only the fields to change' line is helpful but insufficient for a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a compact argument list. It front-loads the core purpose and immediately follows with the key behavioral instruction. Every line adds value, with no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the presence of an output schema, the description covers the essential inputs and the partial-update behavior. It omits edge cases like passing no updated fields or authorization requirements, but these are not critical for a straightforward update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to all parameters by explicitly defining each one (e.g., 'label: New name', 'sql: New SQL query'). This goes beyond the raw schema types and clarifies that only saved_query_id is required, with the others being optional fields to change.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Update a saved query', a specific verb+resource that clearly states the tool's purpose. It distinguishes from sibling tools like create, get, delete, and list by focusing on the update 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'Pass only the fields to change' provides clear guidance on how to use the tool for partial updates. It does not explicitly mention when not to use it or suggest alternatives, but the update context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It adds the engine-compatibility caveat, which is a genuine behavioral trait. However, it does not disclose whether the operation is read-only, what the expected response format is (though an output schema exists), or how cost estimates might vary. The engine note earns some credit, but significant behavioral details remain undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. It uses two introductory sentences and a brief Args block. Every sentence contributes value: the EXPLAIN method, the engine compatibility warning, and parameter semantics. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and only three parameters, the description covers the essential context: what the tool does, the important limitation of engine support, and parameter meanings. It does not explicitly mention the return value, but the output schema fills that gap. The description is complete enough for an agent to decide whether to invoke this tool and how to set parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args section that adds meaning beyond the raw schema: database_id is a 'Database connection ID,' sql is a 'SQL query to estimate,' and schema is described as providing context with an example ('public'). This is helpful because the input schema only lists types and defaults. The one-line explanations are clear and sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Estimate the cost of executing a SQL query (EXPLAIN).' This clearly distinguishes the tool from siblings like superset_sqllab_execute and superset_sqllab_format_sql, making its purpose immediately evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a key usage constraint by stating 'Not all database engines support this feature. PostgreSQL does,' which helps the agent know when it might fail. However, it does not explicitly guide when to choose this tool over alternatives, such as 'use superset_sqllab_execute if you want to run the query directly.' The engine support note is useful but not full when/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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully warns about irreversibility, server lockout, and dashboard access changes. However, it incorrectly states that confirm_delete is 'REQUIRED' while the schema contradicts this by marking it optional with a default of false. This schema-contradiction detracts from full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, a CRITICAL warning section, and a simple Args list. It is concise and front-loaded with the essential action. The only structural flaw is the redundant and incorrect 'REQUIRED' note on confirm_delete, which adds noise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a delete operation with severe consequences, the description covers the most critical side effects: irreversibility, service-account lockout, and dashboard access changes. An output schema exists, so return values need not be detailed. However, it omits other potential consequences like cascading role/permission deletions, and does not mention required admin permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It provides basic explanations for user_id and confirm_delete, but the claim that confirm_delete is 'REQUIRED' is misleading and contradicts the schema. The description fails to clarify the actual optional nature of confirm_delete or its purpose beyond a checkbox, limiting its value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Delete a Superset user.' It uses a specific verb and resource, and distinguishes itself from sibling tools like superset_user_create, superset_user_update, and superset_user_get. The added note 'This operation is irreversible' further clarifies the action's nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use the tool (to delete a user) and includes explicit warnings about dangerous cases (deleting the current service account or dashboard owners). While it does not name alternative tools, the guidance on side effects helps the agent decide when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that overwrite controls replacing existing objects with the same UUID, and that files must be YAML-based. However, it does not specify default behavior when overwrite=False (e.g., error vs skip) or other side effects like dependency imports.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three short sentences plus a brief arg list. It front-loads the main purpose and keeps parameter explanations minimal, earning its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an import operation with dependencies and overwrite semantics, the description covers the essentials but omits return value details, failure handling, and default behavior when overwrite=False. The lack of explicit usage guidance for alternatives also leaves a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema lacks property descriptions (0% coverage), but the description compensates with an Args block defining file_path as an absolute path and overwrite as a toggle for existing UUID objects. This adds meaning beyond the bare types in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Import dashboards from a ZIP file (created via export),' clearly stating a specific verb and resource. It distinguishes from sibling tools like superset_dashboard_export and superset_chart_import by specifying dashboards and ZIP input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: the ZIP should come from an export and contain YAML dashboard/dependency files. However, it does not explicitly state when to choose this tool over superset_assets_import or superset_chart_import, nor does it 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?
With no annotations provided, the description carries the full burden. It discloses a critical behavioral trait: passwords are NOT exported for security reasons. It also clearly specifies the return format as JSON containing base64-encoded ZIP data and size_bytes. However, it does not mention authentication requirements, whether the operation has side effects (e.g., modifies any state), or error behavior for invalid database_ids. Still, the security caveat and return structure add significant transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: a purpose statement, an important security note, an Args section, and a Returns section. Every sentence earns its place; there is no fluff. It is front-loaded with the purpose and critical caveat, making it easy for an agent to scan quickly. The formatting is consistent and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter export tool, the description is quite complete. It specifies the parameter format, the return envelope, and a key security limitation. The existence of an output schema reduces the need to explain return values in full, though the description already does. Missing elements like error handling or what the ZIP contains besides connection configs are not critical for basic invocation but could be considered gaps. Overall, it is well above minimal viability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a string parameter 'database_ids' with no description (schema description coverage is 0%). The description compensates fully by explaining that the parameter takes comma-selected connection IDs and giving an example ('1,2'). This clarifies both the expected format and the meaning of the value, which is essential since the schema alone is ambiguous. For a single parameter, this is high-value semantic addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Export database connection configurations as a ZIP file', which clearly identifies the action (export), the resource (database connection configurations), and the output (ZIP). This distinguishes it from sibling export tools for dashboards, charts, and datasets, as well as from database read operations like superset_database_list and superset_database_get. The safety note about passwords further clarifies what the tool produces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not name any sibling tools as alternatives or state conditions like 'use when you need to back up connections' or 'not for single connection details'. The only hint is the purpose, but that is implied by the action, not a usage guideline. This leaves the agent to infer appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List schemas') but does not mention potential side effects, permissions, pagination, or error conditions. The phrase 'available in a database' adds minimal behavioral context, but overall the description lacks transparency about the tool's behavior beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a clear purpose statement, a usage hint, and a parameter definition. Every sentence adds value and there is no redundant text or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple list operation with an output schema present, the description provides all essential information: what it lists, why to use it, and how to supply the parameter. It does not cover edge cases like unsupported databases, but for the described scope it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only indicates database_id as an integer with no description (schema coverage 0%). The description compensates fully by documenting 'database_id: Database connection ID (from database_list)', which explains what the parameter is and explicitly tells the agent how to obtain it from a sibling tool. This is excellent semantic enrichment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List schemas available in a database', which is a specific verb+resource pair that clearly identifies the operation. It effectively distinguishes from siblings like superset_database_catalogs and superset_database_tables by focusing on schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence 'Useful for selecting a schema before querying tables or creating a dataset' provides clear context on when to use this tool. However, it does not explicitly name alternatives or explain when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses that the copy includes columns and metrics, enforces a unique table_name, and returns a JSON string. However, it does not mention side effects, permissions, or failure behavior for a mutation tool. It 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with Args and Returns sections. Every sentence provides useful information, including the important base_model_id naming warning. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description is complete: it states the operation, parameter meanings, constraints, and return format. It could mention prerequisites like the source dataset existing, but that is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It fully explains both parameters: base_model_id (source dataset ID with a field-name warning) and table_name (unique name for the new dataset). This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a copy'), the resource ('existing dataset'), and the scope ('with columns and metrics'). This distinguishes it from sibling tools like superset_dataset_create (which creates from scratch) and superset_dataset_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when duplicating an existing dataset, but it does not explicitly contrast it with alternatives or state when not to use it. Sibling tools like superset_dataset_create or superset_dataset_import exist, but no exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals the overwrite parameter's effect (overwrite existing objects with matching UUIDs), but does not disclose potential side effects like whether imports can be destructive, permissions required, what happens if a UUID matches without overwrite, or whether partial failures can occur. For a mutation tool, these gaps are significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded with the main purpose, followed by clearly organized Args and Returns sections. Every sentence adds value, with no wasted words or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter import tool, the description covers purpose, parameters, and return value. The existence of an output schema means return details are likely handled elsewhere. It lacks some context about error handling and import scope nuances, but is largely complete for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description includes an Args section that thoroughly documents both parameters: file_path requires an absolute path, and overwrite is a boolean defaulting to False. This adds essential meaning beyond the bare type information in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports datasets from a ZIP file, with a specific action and resource. The sibling list includes superset_dataset_export, superset_assets_import, and superset_chart_import, and this description correctly distinguishes itself by focusing on datasets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'created via export' gives clear context that this tool is for importing previously exported dataset ZIP files, implying it pairs with an export tool. However, it does not explicitly mention when not to use it (e.g., for importing other asset types, use superset_assets_import).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It indicates a read operation via 'Get' and lists return fields, but does not explicitly state authentication requirements (beyond the term 'authenticated'), side effects, or error behavior. For a simple getter this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one short main sentence plus a compact 'Returns' block. No waste, front-loaded with the core purpose, and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter getter with an output schema, the description is complete: it identifies the resource, the action, and the key returned fields. No additional context seems necessary for agent selection or invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline per instructions is 4. The description does not need to explain parameters, and the listed return fields are not parameter-related.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get information') and the resource ('current authenticated user'), and differentiates from the sibling tool superset_get_current_user_roles by listing additional fields (username, name, email, active status). It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like superset_get_current_user_roles or superset_user_get. The usage is implied by the name and description, but no clear context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It does add useful context: 'Users in a group automatically inherit all roles of the group' and notes the name must be unique. However, it does not disclose other behavioral traits such as required permissions, error handling (e.g., behavior if name already exists), or whether this mutation is reversible. This is a moderate disclosure for a create 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a two-sentence conceptual explanation, and a bulleted Args list. Every sentence adds value, examples clarify expected formats, and the structure is easy to scan. There is no redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects for a creation tool: what it does, key behavioral consequence (role inheritance), and parameter semantics. It does not explain the return value or error conditions, but with an output schema present, return value documentation is not required. It is sufficient for an agent to correctly invoke the tool, though it could mention permission requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are explained in the Args section with semantic meaning and examples: name (unique, e.g., 'la_region_Moscow'), label (display label), description, roles (list of role IDs), and users (list of user IDs). The schema provides types/required but no descriptions, so this fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Create a new user group.' It distinguishes itself from sibling tools like superset_group_update or superset_group_delete by specifying the creation action, and provides context about what a group is (combines users and roles), further clarifying the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through 'Create' but this is no explicit guidance about when to use this tool vs alternatives. For example, the description does not mention using superset_group_add_users or superset_group_add_roles for modifying an existing group, nor any prerequisites or exclusions. Those details would clarify when to choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden of behavioral disclosure. It adds valuable context beyond a simple 'Get' by explaining pagination semantics, the 'get_all' automatic-pagination behavior, and filter syntax with concrete examples. It does not mention permissions, rate limits, or side effects, but for a read-only list operation this is fairly 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose clearly front-loaded, followed by a compact list of arguments and examples. Every sentence provides necessary information—no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and all four parameters thoroughly documented, the description is largely complete. The only notable gaps are the absence of explicit differentiation from similar audit/recent-activity tools and lack of operational details like rate limits or error handling, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must fully explain the parameters. It does so comprehensively: page (start at 0), page_size (max 100), q (with two examples), and get_all (ignores page/page_size). This adds meaning far beyond the bare schema properties and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get the audit log of all Superset user actions', which is a specific verb+resource combination. It clearly identifies the tool's function, but it does not explicitly differentiate this from siblings like 'superset_permissions_audit' or 'superset_recent_activity', so it stops short of full distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed parameter usage and examples (e.g., RISON filters for user/action), which implies when to use the tool for audit log queries. However, there is no explicit guidance on when to prefer this over alternative tools, nor any exclusions or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral transparency burden. It discloses important behaviors such as username/email uniqueness, the default role (Public) when roles are omitted, and active defaulting to True. However, it does not mention permissions required, failure modes, or other side effects of creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single purpose sentence followed by a clear Args list. Each line adds meaningful information, 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters and no annotations, the description covers all inputs, defaults, and key constraints, and the output schema likely covers return values. It lacks explicit permission or error-handling context, but it is still largely complete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameter descriptions, but the Args section fully compensates by explaining every parameter: first_name, last_name, username, email, password, roles, and active. It adds details beyond the schema, such as uniqueness constraints, role source, and default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create a new Superset user.' This clearly states the tool's action and object, and distinguishes it from sibling tools like superset_user_update, superset_user_get, and superset_user_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the 'Create' verb and provides useful context like role IDs coming from superset_role_list, but it never explicitly states when to use this tool vs. alternatives or when not to use it. There is no direct comparison with other user-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the base64-encoded ZIP return format and the import compatibility, but it does not state whether the operation is read-only, any error behavior, or potential size/performance implications. This leaves some gaps in behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose, a brief note on the output format and import workflow, and clearly labeled Args and Returns sections. Every sentence adds value, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter tool, the description covers the purpose, input format, and return structure. It lacks error-handling details and explicit safety statements, but with the included Returns JSON example, it is sufficiently complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter (chart_ids) with no description (0% coverage). The description's Args section explicitly defines the comma-separated format with an example, adding meaning beyond the schema. This sufficiently compensates for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Export') and identifies the resource ('charts') with the key differentiator 'with all dependencies (datasets, databases)' and the output format 'as a ZIP file'. This clearly distinguishes it from other export tools like superset_dashboard_export or superset_assets_export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides context that the tool exports charts with dependencies for backup/migration and mentions it can be imported back via superset_chart_import. However, it does not explicitly mention alternative tools or exclusions, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It reveals output content but omits potential errors, permission requirements, or confirmation that this is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-line purpose, a returns list, a critical usage note, and a parameter definition. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with an output schema, the description covers purpose, return fields, and parameter provenance. It lacks error handling notes but is otherwise sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines chart_id as an integer with no description; the description compensates by stating it comes from the chart_list result, adding practical source context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves detailed chart information by ID and lists specific settings returned (viz_type, params, query_context, dashboard bindings), distinguishing it from list/data tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs users to call superset_chart_list when the ID is unknown, providing a clear workflow gate. However, it does not contrast with other chart-related tools like superset_chart_get_data or superset_chart_data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden of behavioral disclosure. It discloses the 404 error condition and the dependency on a prior embedded_set call, which is valuable beyond the name/schema. It does not cover auth or response format, but the presence of an output schema mitigates that. Overall, it adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise: a one-line purpose, a critical IMPORTANT note, and a simple Args section. Every sentence earns its place. The important warning is front-loaded, making it easy for the agent to notice. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one integer parameter) and the presence of an output schema, the description provides sufficient context. It covers the essential behavior (404 if not configured) and the prerequisite relationship. It is complete for a getter tool of this scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only states 'dashboard_id: Dashboard ID,' which is essentially a restatement of the parameter name and adds no new meaning (e.g., format, source, constraints). The schema already provides the type as integer, so the description contributes little to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the embedding (embedded) settings of a dashboard.' It uses a specific verb ('Get') and resource ('dashboard embedded settings'), and the sibling tools (embedded_set, embedded_delete) are distinct by operation. The purpose is unambiguous and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes a key prerequisite: the tool returns 404 if embedded mode has not been configured via embedded_set. This tells the agent when to use it (after setup) and provides a practical constraint. It does not explicitly name alternatives, but the sibling names make the distinction obvious. This is clear guidance, though not fully exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that confirm_delete is REQUIRED, indicating a deliberate safety step for a destructive operation. It also specifies the expected filter_id format ('NATIVE_FILTER-<uuid>'), which is valuable behavioral context. However, it does not explicitly state that deletion is permanent or irreversible, though this is implied by the confirmation requirement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence stating the action, followed by a compact Args list. Every line adds necessary information with minimal redundancy. It is concise and structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward delete tool with three parameters, the description covers the key inputs and includes a critical confirmation flag. It does not mention permissions or error conditions, but the output schema exists to explain returns, and the tool's simple action does not require extensive additional context. The description is adequate for a user to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter descriptions, so the description compensates by explaining all three parameters: dashboard_id (Dashboard ID), filter_id (ID of the filter to delete with format), and confirm_delete (Deletion confirmation REQUIRED). This adds meaning beyond the raw schema, especially for filter_id and confirm_delete, though it could be more explicit about confirm_delete being a boolean set to true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete a native filter from a dashboard by ID.' It clearly identifies the action (delete), the target (native filter), and the scope (from a dashboard). This distinguishes it from related sibling tools like superset_dashboard_filter_add or superset_dashboard_filter_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing a native filter from a dashboard, but it does not explicitly state when to use this tool versus alternatives like update or reset. It provides no exclusionary context or mention of other filter operations, leaving the agent to infer the appropriate scenario.
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?
Without annotations, the description carries the transparency burden. It discloses partial-update behavior and special meanings (None removes cascading, empty filter = NULL). However, it omits permission requirements, reversibility, and side effects, leaving gaps for a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a concise overview followed by a structured argument list. Every line serves a purpose, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a moderately complex update operation with 8 parameters. The description covers all parameters, partial-update behavior, and special value semantics. An output schema exists, so return values are not needed. Missing details like failure modes or prerequisites are acceptable for this scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides a one-line explanation for every parameter, including the filter_id format and the special None behavior for cascade_parent_id. Some explanations are terse but add meaning beyond raw types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Update a native filter on a dashboard by ID', using a specific verb and resource. It clearly distinguishes this tool from sibling filter operations like add, delete, and reset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Pass only the fields to change' conveys partial-update semantics and implies this is for modifying an existing filter. It does not explicitly name alternatives, but the sibling tool list and the update-focused wording make the use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains the post-condition: the dashboard remains accessible to owners/admins but is hidden from the general list. This is meaningful context beyond the simple 'unpublish' action, though it doesn't cover permissions or side effects like whether embedded views are affected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a single-arg line, front-loaded with the action. Every sentence earns its place; the Args section is slightly redundant but acceptable for such a short description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description explains the operational effect (convert to draft, hidden from general list) and the exception for owners/admins. It omits prerequisites like 'the dashboard must be currently published,' but this is implied by the action and the sibling tool superset_dashboard_publish. Overall, it is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description repeats 'dashboard_id: Dashboard ID' with no additional semantics. The single integer parameter is self-explanatory from its name alone, so the description adds little value beyond the schema. It does not compensate for the lack of schema documentation, but it's not misleading.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Unpublish a dashboard (convert to draft).' It distinguishes from siblings like superset_dashboard_publish and superset_dashboard_delete by explaining the resulting state (hidden from general list, but accessible to owners/admins).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when a dashboard should be hidden from the general list but remain accessible to owners/admins. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It discloses a key behavioral trait: not all engines support catalogs, with common examples. However, it does not explicitly state that the operation is read-only or what happens on unsupported engines (error vs empty).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs and an Args line; every sentence is informative. The main purpose is front-loaded, and the caveat is placed early.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and likely a straightforward output. The description covers purpose, engine support limitation, and parameter semantics. It doesn't need to explain return values because an output schema is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for database_id (0% coverage), but the description compensates with an Args section explaining it as 'Database connection ID.' This adds meaning beyond the raw integer type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List catalogs in a database' with a specific verb and resource, and distinguishes itself from sibling tools by focusing on catalogs (versus schemas or tables). The engine-support caveat further narrows its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides when-to-use guidance by limiting to engines that support catalogs, and gives when-not examples (PostgreSQL and MySQL). However, it does not explicitly reference alternative tools such as superset_database_schemas or superset_database_tables, so it lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of disclosing behavior. The verb 'Get' implies a read-only operation, which is useful. However, it does not mention authentication requirements, error handling (e.g., invalid ID), or any side effects. The description is not misleading but is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the purpose in the first sentence. The IMPORTANT note is relevant and the Args section is clearly formatted. Every line earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with one parameter, the description covers the purpose, prerequisite, and parameter meaning. The output schema exists, so return values need not be described. It could mention what happens if the ID is not found, but overall it is adequate 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'database_id' as an integer, but the description adds valuable context: 'Connection ID (integer from database_list result).' This tells the agent where to obtain the ID and reinforces its type, going beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get detailed information about a database connection by ID.' This uses a specific verb ('Get'), identifies the resource ('database connection'), and specifies the scope ('by ID'). It also implicitly distinguishes from the list sibling by requiring a known ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'IMPORTANT: if the ID is unknown, call superset_database_list first.' This tells the agent when to use this tool vs. an alternative (list). It does not mention when not to use it or other alternatives like connection_info, but the core context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It does explain the schema default behavior and that the query includes a LIMIT. However, it does not explicitly state whether the tool executes the query or merely returns the SQL text, and it does not mention any permissions or side effects. This ambiguity prevents a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose, followed by a structured Args list that adds necessary semantic details. The Args list is a bit redundant with the schema parameter names but justifies its presence by providing explanations. It is efficient and well-organized, though not maximally compact.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, with 3 parameters and an output schema present. The description explains all parameters and provides usage context. It does not mention the exact LIMIT value or explicitly state that the query is not executed, but given the output schema and the straightforward nature of the tool, the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions for parameters, so the description carries the full burden. It clearly explains all three parameters: database_id is the 'Database connection ID', table_name is the 'Table name', and schema_name is the 'Schema (e.g. "public"). If not specified, uses the default schema.' This adds complete meaning beyond the bare schema, fully compensating for zero schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Generate a SELECT * SQL query for a table (with LIMIT).' This is a specific verb+resource combination that distinguishes it from siblings like superset_database_table_metadata (which retrieves metadata) and superset_sqllab_execute (which executes queries). The purpose is immediately understandable 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: 'Useful for quickly inspecting table structure and data.' This implies when to use the tool, but it does not explicitly mention alternatives or when not to use it. Since it gives a clear context without exclusions, it earns a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses that the tool returns name, label, description, roles, and users, and the phrase 'Get detailed information' implies a read-only operation. However, it does not disclose behavior for missing IDs, permission requirements, or possible errors, which are minor gaps for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a returns line, and an Args line. Every sentence adds value, and the most important information (what the tool does and what it returns) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema, the description covers the essential aspects: purpose, return value, and parameter sourcing. It does not elaborate on error cases or authentication, but given the tool's simplicity and the presence of an output schema, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so by describing the parameter as 'Group ID (from group_list)', which adds the source context beyond the schema's bare 'integer' type. This gives the agent actionable guidance on where to find the ID, fully covering the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get detailed information about a group by ID', which uses a specific verb (get), a clear resource (group), and a clear scope (by ID). It distinguishes the tool from siblings like superset_group_list (which lists groups) and superset_group_update/delete, and the returned fields (name, label, description, roles, users) further clarify the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool provides clear context by stating the parameter is 'Group ID (from group_list)', which implies a prerequisite step of calling superset_group_list to obtain the ID. This gives a usage flow, though it does not explicitly state when to avoid this tool or mention alternatives like superset_group_role_get or superset_group_user_get.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It explains pagination behavior, especially the 'get_all' parameter that 'ignores page/page_size', and clarifies that permissions are combinations of actions and resources. It does not mention authentication or rate limits, but for a read-only list operation, the disclosed behavior is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, a brief contextual sentence about permission structure, and a focused Args list. No redundant information, and the key points are front-loaded. It is slightly longer than strictly necessary but remains concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the presence of an output schema, the description is complete for a list operation. It covers the purpose, parameter semantics, and the nature of the returned data. It lacks guidance on when to use it relative to sibling tools, but that is a usage guideline matter rather than a completeness gap here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must define parameters. The Args section does this thoroughly: page describes start from 0, page_size explains default 100, q identifies as a RISON filter, and get_all specifies automatic pagination and that it ignores other pagination params. This fully compensates for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the list of all available permissions (permission_view_menu) in Superset.' It specifies the resource and action, and distinguishes it from other permission-related tools by focusing on listing all permissions. The explanation of permission composition (action + resource) reinforces its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one needs to retrieve all available permissions, but it does not explicitly compare with alternatives like superset_permissions_audit or superset_role_permissions_get. It provides context but lacks when-not-to-use or exclusionary 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that deleting an RLS rule lifts restrictions for associated roles and highlights the severe security risk of deleting deny-by-default rules (clause='1=0'), which would expose ALL data. It does not mention irreversibility or permissions, but the disclosed risk is meaningful and goes beyond the bare delete action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-sentence purpose, a prominent CRITICAL warning, and a compact Args list. No redundant or filler content. Each sentence earns its place, and the most important safety information is front-loaded with ALL CAPS emphasis.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not explain return values. It covers the tool's purpose, the key security risk, and all parameter semantics. However, it would benefit from explicitly stating that confirm_delete must be set to true to actually perform the deletion, since the schema default is false and the description only marks it as 'REQUIRED'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by providing an Args section. It explains rls_id as the ID of the RLS rule to delete and confirm_delete as a required deletion confirmation. It also introduces the domain-specific concept of clause='1=0' for deny-by-default rules. This adds significant meaning beyond the raw schema which only gives types and a default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete an RLS rule' which is a specific verb+resource statement. It clearly distinguishes this tool from siblings like superset_rls_create, superset_rls_update, and superset_rls_get by stating the delete action and its immediate effect on role restrictions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the verb 'delete' and explains the consequence, but it does not explicitly state when to choose this tool over alternatives like superset_rls_update or provide any exclusion criteria. The critical warning serves as a caution rather than a usage guideline. No alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses one behavioral nuance: get_all ignores page/page_size. It also explains what RLS is. However, it does not mention permissions, error conditions, or whether the list is scoped to the current user or includes all rules. For a read-only list tool, 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and includes a structured Args block. It is a bit longer than necessary, but every line provides useful information. The RLS context sentence is a helpful addition, not wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (though not shown) and this is a simple paginated list tool, the description covers purpose, parameters, and one behavioral quirk. It lacks explicit guidance on how this relates to superset_rls_get (singular) or any security context, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents all four parameters with meaningful details: page (starting from 0), page_size (max 100), q (RISON filter for searching), and get_all (ignores page/page_size). This adds significant value beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Get the list of Row Level Security rules.' It also adds a brief explanation of RLS ('adds a WHERE clause to queries for specific roles'), which clarifies the domain. The name and description clearly distinguish this from sibling tools like superset_rls_get, superset_rls_create, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool via its purpose and includes parameter-level guidance (e.g., get_all for automatic pagination). However, it does not explicitly compare with alternatives such as superset_rls_get or mention scenarios where it should not be used. This is clear context but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does add valuable context by clarifying that the role is created without permissions and that the name must be unique. However, it does not disclose other behaviors such as error responses, authentication requirements, or whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences followed by a compact args list. It front-loads the core purpose and uses no filler, making it easy for an agent to parse and act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and there is only one parameter, the description is largely sufficient. It covers the essential purpose and a key constraint, and correctly references the companion tool for permissions. It could be slightly more complete by mentioning what the response includes, but this is covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines 'name' as a string, but the description enriches this by adding 'Role name (must be unique)' — providing a crucial constraint not present in the schema. This compensates for the low schema description coverage and helps the agent understand the parameter's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create a new role (without permissions).' This uses a specific verb and resource, and distinguishes the tool from siblings by explicitly noting that permissions are not included, pointing to the separate tool 'role_permission_add' for that functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating that permissions are added via 'role_permission_add', implying when to use this tool (initial role creation) and when to use an alternative (permission assignment). However, it does not explicitly mention other sibling tools or state exclusions for cases like updating or deleting roles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the consequential effect (users lose permissions) and emphasizes that confirm_delete is required. However, it does not state whether deletion is permanent or irreversible, which is a notable omission for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, with a one-line purpose, a clear blocklist, and an Args section. Every sentence provides necessary information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive delete tool, the description covers the key aspects: what it does, the consequence, and a critical safety parameter. It does not mention return values, but an output schema exists. The minor gap is lack of clarity about irreversibility and the confirm_delete requirement conflict with the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by naming and explaining role_id and confirm_delete beyond the bare schema. However, calling confirm_delete 'REQUIRED' contradicts the schema's required list (only role_id is required) and default value (false). This inconsistency could mislead an agent about whether the parameter must be supplied or set to true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Delete a role.' It further clarifies the impact ('Users with this role will lose the associated permissions'), which distinguishes it from related role tools like update or create. The purpose is unmistakable 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states a when-not condition by listing system roles that are blocked from deletion. It does not name alternative tools, but the delete operation is distinct enough that the lack of explicit alternatives is acceptable. The context is clear 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a key environmental dependency (Results Backend), but it does not state whether the operation is read-only, what happens if the backend is missing, or any other side effects. This adds some but not comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action, followed by an important prerequisite note and a structured Args section. Every sentence earns its place, with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter export tool, the description covers the primary purpose, a critical prerequisite, and parameter provenance. The output schema likely handles return format details, so no further explanation is needed. However, it could more explicitly state the dependency on a prior execute call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the parameter, but the description compensates with an Args section explaining that client_id comes from superset_sqllab_execute. This provides meaningful provenance and purpose beyond the schema's bare 'string' type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Export') and resource ('query results to CSV format'). It also references the client_id from superset_sqllab_execute, which distinguishes this from other SQL Lab tools like superset_sqllab_results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite (configured Results Backend) and indicates the client_id comes from a prior superset_sqllab_execute call, giving context on when to use the tool. However, it does not explicitly mention alternatives or when not to use it beyond the backend requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the backend dependency and the 500 error condition, but omits other behaviors such as what happens when the key is missing or whether retrieval affects the stored result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear opening sentence, a short important warning, and a parameter definition. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter retrieval tool with an output schema, the description covers the purpose, prerequisite, and key source. It could also mention alternative query information sources, but it's complete enough for typical usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only identifies a string parameter with no description; the tool description adds crucial meaning by explaining it is the results_key from the sqllab_execute response. This adequately compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Retrieve results of a previously executed query by key' with a specific verb and resource. It clearly distinguishes itself from sibling sqllab tools like execute and export.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions the prerequisite (Results Backend) and failure mode (500), and directs the user to obtain results_key from sqllab_execute response. This gives clear context, though it doesn't explicitly name alternative 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?
With no annotations, the description carries the burden and discloses key behavioral traits: the destructive side effect of removing all object attachments and the mandatory confirmation. It does not mention irreversibility or permissions, but these are implied by 'delete'. The confirmation requirement adds important 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the main action, followed by the side effect and a structured Args section. Every sentence adds value with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description covers the primary purpose, side effects, and parameter meanings. It lacks explicit detail about what happens if confirm_delete is false or if the tag does not exist, but the presence of an output schema mitigates the need to document return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains both parameters: tag_id as the ID to delete and confirm_delete as deletion confirmation. Since the input schema has 0% description coverage, this fully compensates. However, it declares confirm_delete as REQUIRED while the schema marks it optional with default false, creating a minor inconsistency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a tag' with specific verb and resource, and adds the side effect that all object attachments will be removed. This distinguishes it from sibling tag operations like get, update, list, or bulk_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the delete action and the explicit requirement for confirm_delete, but no explicit alternatives or when-not-to-use conditions are provided. The confirmation requirement serves as a basic usage guideline.
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?
There are no annotations, so the description carries the full burden of behavioral disclosure. However, it only states the purpose and does not mention potential errors (e.g., if the tag ID does not exist), authentication requirements, or any side effects. While the 'get' implies a read operation, the description does not explicitly disclose behavior beyond the basic retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, consisting of one purpose statement, an important usage note, and a parameter definition. Every sentence contributes useful information without redundancy. The key information is front-loaded, and the important note is clearly emphasized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 'get by ID' tool, the description covers the essential aspects: purpose, prerequisite, and parameter semantics. An output schema is present, so return values do not need to be explained. The only minor gap is the lack of error handling or not-found behavior, but this is not critical given the tool's simplicity. Overall, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema only defines tag_id as an integer, but the description adds meaning by specifying 'Tag ID (integer from tag_list result).' This clarifies the origin and type of the parameter, which is valuable given the schema description coverage is 0%. It adequately compensates for the lack of schema descriptions, explaining that the ID comes from the list operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get tag information by ID.' This is a specific verb+resource indicating a lookup operation. It distinguishes itself from sibling tools like superset_tag_list (which lists tags) and superset_tag_get_objects (which retrieves objects associated with a tag), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes an explicit usage guideline: 'if the ID is unknown, call superset_tag_list first.' This tells the agent when to use this tool compared to the list alternative, providing clear context and a direct prerequisite. It effectively communicates the condition under which this tool should be invoked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It implies a read-only operation via 'Get' and adds the dependency note about user_list, but it does not state permissions required, behavior for invalid IDs, or whether any side effects occur. This is minimally adequate but lacks deeper transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, starting with a clear purpose, followed by an important usage note, and a compact Args section. Every sentence earns its place, with no redundant information or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter) and the presence of an output schema, the description does not need to explain return values. The prerequisite to call superset_user_list for unknown IDs is valuable contextual completeness, though it avoids discussing not-found errors or permission issues, which would have made it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no property descriptions (0% coverage), so the description compensates by explaining user_id as 'User ID (integer from user_list result).' This adds meaning by specifying data type and origin, though it stops short of detailing constraints like required existence or validation behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('detailed information about a user by ID'), distinguishing it from sibling tools like superset_user_list (which likely returns all users) and superset_get_current_user (which targets the current user). The inclusion of 'by ID' makes the scope 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs calling superset_user_list first when the ID is unknown, providing a clear prerequisite and alternative workflow. However, it does not mention when to use alternative getter tools (e.g., superset_get_current_user) or when not to use this tool, leaving some gaps in full alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey safety and side-effect behavior. It discloses the ZIP requirement (must contain YAML configs and dependencies) and the overwrite parameter, but it doesn't mention failure modes, whether existing charts are updated when overwrite is true, or dependency handling details. This is a moderate level of transparency for a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-line purpose statement, a brief note on ZIP contents, and a clear Args block. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with an output schema, the description covers the key operational aspects: source format, dependency requirement, and overwrite behavior. It doesn't detail error handling or edge cases like missing dependencies, but that isn't necessary for minimal viable completion. The presence of an output schema means return values are already defined elsewhere.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only gives types and defaults with 0% coverage. The description fully compensates by explaining file_path as an absolute path on disk and overwrite as controlling whether to overwrite objects with the same UUID, adding meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool imports charts from a ZIP file created via export. This distinguishes it from sibling tools like superset_dashboard_import, superset_dataset_import, and superset_assets_import by specifying the resource type as 'charts'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description notes the ZIP file is 'created via export', which implies this tool is for restoring previously exported charts. This provides clear context for when to use it, though it doesn't explicitly discuss alternatives or when not to use it beyond the implicit distinction from other import tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the transparency burden. It adds useful behavioral detail by noting that Superset requires json_metadata (defaulting to '{}') and that the copy includes 'all its charts'. However, it does not disclose whether the copy is published, how permissions are handled, or what happens if the source dashboard is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the main purpose, followed by a simple parameter list. Every sentence adds value, with no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return-values need not be described. The description covers all parameters, notes a crucial requirement (json_metadata), and clearly states the tool's scope. Minor gaps remain (e.g., prerequisites or error behavior), but overall it is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section elaborates on all three parameters: dashboard_id is the source, dashboard_title is the new title, and json_metadata is the JSON metadata with an important note. Since the schema has no descriptions (0% coverage), this fully compensates and adds semantic meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Create') and resource ('a copy of an existing dashboard with all its charts'). This distinguishes it from sibling tools like superset_dashboard_create (new dashboard) and superset_chart_copy (single chart), making the intent unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you need to duplicate an existing dashboard. It does not explicitly name alternatives, but the 'existing dashboard' qualifier and mention of charts make the use case clear, without needing to exclude other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It clarifies that it lists both tables and views and scopes to a specific schema, but it does not explicitly state read-only behavior, permission requirements, or error handling. The verb 'List' implies safety, but this is not formally disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with purpose, followed by a concise Args block. Every sentence contributes context without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations but a rich output schema, the description covers purpose, usage, and parameters thoroughly. It does not mention pagination or potential errors, but these are not essential for a straightforward listing tool, so it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description fully compensates by explaining database_id comes from database_list, schema_name from database_schemas, providing examples, and noting the RISON format without quotes. This adds meaning far beyond the plain integer/string schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List tables and views in the specified database schema,' which is a specific verb+resource+scope statement. It clearly distinguishes this tool from siblings like superset_database_schemas (which lists schemas) and superset_database_table_metadata (which likely gets table details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is 'Useful for selecting a table before creating a dataset,' giving clear context for when to use it. It does not mention alternatives or explicit exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the critical destructive consequence and mentions the need for confirmation. However, the 'REQUIRED' label for confirm_delete conflicts with the schema's optionality, creating slight ambiguity about the actual deletion behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, with a clear structure: action, warning, Args, Returns. However, 'Charts using this dataset will stop working' and the subsequent CRITICAL sentence are redundant, so not every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params) and the presence of an output schema, the description covers the essential context: what it does, the major risk, argument meanings, and return type. It lacks details such as permission requirements or explicit confirmation semantics, but is largely complete for a delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's Args section explains both parameters: dataset_id as the ID and confirm_delete as 'Deletion confirmation (REQUIRED).' This adds meaning beyond the schema, though it doesn't clarify that confirm_delete must likely be true to proceed, and the 'REQUIRED' wording is inconsistent with the schema making it optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a dataset.' It names the specific resource (dataset) and is distinct from sibling tools like create/update. The additional consequence 'Charts using this dataset will stop working' further clarifies the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context by warning about breaking linked charts and dashboards, signaling this is a destructive operation. However, it does not explicitly state when not to use it or mention alternatives, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses significant behavior: the result is a base64-encoded ZIP, includes dependencies, and returns a specific JSON structure with 'format', 'encoding', 'data', and 'size_bytes'. This is detailed and goes beyond a simple 'export' statement. However, it lacks information about potential side effects or permissions, which would be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-organized with a summary, a note on encoding/import, and clear Args/Returns sections. Every sentence contributes useful information without fluff. It front-loads the main purpose and keeps the structure easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description covers purpose, parameter format, return format, and import compatibility. It does not mention potential errors or size limits, but these are not critical for a simple export tool. Overall, it is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines dataset_ids as a required string with no description. The description explains 'Comma-separated dataset IDs (e.g. "1,2,3")' in the Args section, adding critical semantic information about the parameter's format and expected values. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Export datasets with dependencies (databases) to a ZIP file.' This clearly identifies the resource (datasets), the operation (export), and the output format (ZIP). It distinguishes itself from sibling tools like superset_dashboard_export and superset_database_export by mentioning 'datasets' and 'dependencies'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'Can be imported via dataset_import,' which provides a complementary use case but does not explicitly state when to prefer this tool over alternatives or provide exclusions. It lacks guidance like 'Use this instead of X when...' so the usage context is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the tool 'Returns' the URL, implying a read operation, but doesn't disclose any other behavioral details such as authentication requirements or potential errors. Minimal but adequate for a simple getter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the main purpose. No wasted words; every sentence adds relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple zero-parameter tool with an output schema present. The description explains both what it does and what it returns, fully covering the necessary context. No gaps appear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is trivially complete. Per the baseline for 0 params, a score of 4 is appropriate since no parameter explanations are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the base URL of the configured Superset instance' with a specific verb and resource. It is unique among siblings, as no other tool mentions base URL retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context by explaining the URL is the one used by the MCP server to connect to Superset. It doesn't explicitly discuss alternatives, but no sibling tool serves the same purpose, so the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It reveals that the menu structure reflects the current user's permissions (variability) and is read-oriented ('Get'), but it does not explicitly state safety (no side effects), authentication requirements, or potential empty responses. It adds some context beyond the name but lacks full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the main action and followed by a value-adding use case. There is no redundant or extraneous wording—every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, a likely straightforward output), the description is complete: it states what the tool returns (menu structure) and why it matters (permissions/sections). The presence of an output schema covers return format details, so no further elaboration is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 there are no parameter semantics to explain. Per the rubric, 0 parameters earns a baseline 4. The description adds no parameter-related detail, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool gets the 'Superset navigation menu structure,' using a specific verb and resource. It also adds context ('useful for understanding available sections and the current user's permissions') that clarifies the intent and distinguishes it from other Superset tools focused on roles, users, or dashboards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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: to understand available UI sections and the user's permissions. While it does not explicitly name alternatives like superset_get_current_user_roles or superset_permission_list, it implies a distinct use case without exclusions, meeting the level for clear 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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It goes beyond a simple read operation by explaining the exact calculation logic (dashboard visibility AND data access), the possible value 'visible_no_data' meaning 'can open but charts fail,' and that admins have access to everything. It does not mention auth requirements or rate limits, but given the tool's nature, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an initial overview, bullet-pointed output details, and a clear Args section. It is relatively lengthy, but each part adds necessary information for a complex audit tool. The front-loaded purpose sentence is strong, and the layout makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description still provides substantial context beyond the schema. It explains the output structure, the logic behind access values, the RLS regions, and parameter behaviors. This makes the tool's behavior fully understandable without needing to invoke it experimentally.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter meaning. The 'Args' section provides complete semantics for all four parameters, including types, defaults, constraints (max 50 pages), and behavior (substring match for username, admin inclusion). This fully compensates for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Audit access rights: user x dashboards/datasets/RLS permission matrix,' which clearly specifies the tool's purpose and scope. This distinguishes it from sibling tools like superset_permission_list or superset_role_permissions_get, which focus on simpler permission listings rather than a comprehensive per-user audit across multiple resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for auditing access rights and provides a detailed breakdown of what it returns, giving context for when to use it. However, it does not explicitly contrast with alternatives such as superset_user_list or superset_role_permissions_get, nor does it state when NOT to use it. Thus, usage guidance is mostly implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly indicates a read-only operation ('Get') and adds a valuable behavioral insight about the ordering requirement with role_permission_add. However, it doesn't describe the response format or any potential limitations, which is a slight gap for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences and a parameter line. It is front-loaded with the main purpose, followed by a critical warning, and ends with the parameter definition. No words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and an output schema, the description is largely complete. It includes the essential sequencing caveat that prevents data loss. The only minor omission is guidance on how to find role IDs, but that doesn't significantly impede understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for parameters, so the description must compensate. The phrase 'role_id: Role ID' merely restates the parameter name without adding meaningful context such as where to find the ID or its expected format. This is barely more than the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets the current list of permissions for a role, using a specific verb and resource. This distinguishes it from sibling tools like role_permission_add and role_get, especially with the added note about its role in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to call this tool BEFORE role_permission_add and explains the consequence (avoiding loss of existing permissions). This provides a clear when-to-use scenario and names a specific alternative, making usage guidance unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It reveals the 1000-row limit, default schema behavior, catalog optionality, and template_params usage. However, it does not explicitly warn that arbitrary SQL can include destructive operations or that permissions may be required. The 'IMPORTANT' caution is a general warning but lacks specificity about 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a front-loaded purpose, a cautionary note, metadata tool pointer, row limit, and a parameter list. Every section adds value and the length is justified by the need to document six parameters thoroughly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of an output schema means return values need not be documented. The description covers prerequisites, limitations, and all parameters with examples. It does not mention error handling or asynchronous execution, but overall it is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters are explained in detail with examples for sql and template_params, default behavior for schema, and provenance for database_id. This fully compensates for the 0% schema_description_coverage and significantly adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes a SQL query via SQL Lab and returns the result, distinguishing it from siblings like superset_sqllab_export_csv (which exports) and superset_sqllab_format_sql (which formats). The action and output are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for use (executing validated SQL queries) and references superset_database_table_metadata and superset_database_tables as prerequisite tools for schema discovery. It also notes the 1000-row limit, but does not explicitly state when to prefer alternative execution tools or exclude this tool for certain query types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It explains the input format and allowed object types, which is useful, but does not disclose side effects (e.g., behavior if tags already exist, partial failure handling, permissions required, or atomicity). This is a significant gap for a mutation 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a brief explanation, and an Args section with a detailed example. It is not overly verbose, and each sentence adds necessary information about the complex JSON format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers the input format, which is the main complexity. Since an output schema exists, return values don't need explanation. Minor gaps remain around edge cases like duplicate tags or invalid object IDs, but the description is largely complete for a bulk-create tool with a single parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only 'tags' as a string with 0% description coverage. The description compensates fully by providing a concrete JSON format example, explaining the structure of objects_to_tag as [object_type, object_id], and listing allowed object types. This gives the agent complete parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Bulk-create tags with object attachments,' specifying the action (bulk-create), resource (tags), and scope (with object attachments). It clearly differentiates from sibling tools like `superset_tag_create` (single create) and `superset_tag_get_objects` (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the tool is for 'creating multiple tags and attaching them to objects in a single request,' giving clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, but the bulk vs. single distinction is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It goes beyond a simple statement by adding 'CRITICAL: deletes the layer AND all annotations within it permanently,' highlighting irreversibility and cascading scope. It also flags confirm_delete as required, adding behavioral nuance. It doesn't mention permissions or error cases, but for a delete tool this is substantial coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear action sentence, a critical warning, then bullet-like args. No unnecessary words, and the most important info (permanence) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature, the description covers the essential context: what is deleted, permanence, and the required confirmation. Since an output schema exists, return values don't need explanation. It omits details like permissions or side effects on other objects, but for a deletion tool with two parameters, this suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining both parameters: 'annotation_layer_id: Layer ID to delete' and 'confirm_delete: Deletion confirmation (REQUIRED).' It provides essential meaning beyond the bare schema types. The required flag on confirm_delete may conflict with the schema's optional/default behavior, but it adds clarity about the tool's operational requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Delete an annotation layer along with all its annotations.' It specifies the exact resource (annotation layer) and scope (all its annotations), distinguishing it from sibling tools like deleting a single annotation or updating a layer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for deleting an entire annotation layer and its annotations, not individual annotations. It does not explicitly name alternatives or provide when-not-to-use guidance, but the purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of conveying that this is a safe, read-only operation. The verb 'Get' implies non-mutating behavior, but the description does not explicitly state that it has no side effects or mention potential error outcomes (e.g., 404 if ID not found). It adds the useful context that the ID must be obtained from a list operation, but no deeper behavioral disclosures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with a clear one-sentence summary followed by a crucial usage note and a brief parameter explanation. Every sentence adds value; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with an output schema, the description provides sufficient context: what it does, how to obtain the ID, and the prerequisite list call. It does not explain return values, but the output schema covers that. It could have mentioned that this returns layer metadata only (not the annotations within the layer), but the tool name and sibling context make that reasonably clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining the parameter's meaning and source: 'Layer ID (from annotation_layer_list).' This tells the agent where to obtain a valid value, adding context beyond the schema's bare 'integer' type. It does not elaborate on format constraints, but the schema already provides type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches annotation layer information by ID, using the specific verb 'Get' and naming the resource. It distinguishes this from the sibling tool annotation_layer_list, which retrieves layers without an ID, by explicitly framing it as a lookup by ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'if the ID is unknown, call annotation_layer_list first.' This not only tells the agent when to use this tool (when ID is known) but also names a specific alternative and precondition. The Args section reiterates that the ID comes from annotation_layer_list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses a key behavioral trait: dashboard bindings are NOT copied and must be specified via the dashboards parameter. It also states that all visualization parameters, type, dataset, and query_context are copied. This gives the agent a clear safety profile for a mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and well-organized: a one-line purpose, a two-line behavioral note, and a tidy Args list. Every sentence earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no schema descriptions, the description covers the essential behavior and all three parameters. It does not discuss error scenarios or side effects, but the presence of an output schema likely handles return value expectations, making this sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero property descriptions, so the description's Args section is the only source of parameter meaning. It explains chart_id, slice_name, and dashboards, including that dashboards is optional and used for binding the copy. This adds value beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a copy of an existing chart with a new name,' using a specific verb (copy) and resource (chart). It clearly distinguishes from sibling create/update tools by explaining exactly what is copied (visualization parameters, type, dataset, query_context) and what is not (dashboard bindings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: when a duplicate of an existing chart is needed, it copies all relevant settings while allowing new dashboard bindings. However, it does not explicitly mention alternatives like superset_chart_create or superset_chart_update, so there are no exclusionary statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the key prerequisite (query_context) and the fallback action, which is critical behavioral context. However, it does not mention error handling, response format details, or whether any side effects occur, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct, front-loaded with the core purpose, followed by the critical IMPORTANT note, and concluding with the parameter list. Every sentence adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with an output schema and a moderate complexity, the description covers the main trap (missing query_context) and directs the user to the correct alternative. It does not elaborate on expected output structure, but the output schema covers that. Overall, it is sufficiently complete for usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It provides 'chart_id: Chart ID', which is minimal but aligns with the schema. It adds no extra meaning beyond the property name and type, but the parameter is self-explanatory. The description does not explain how to obtain the chart ID or any constraints beyond the integer type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get data from a specific saved chart by its ID', with a specific verb and resource. It distinguishes itself from sibling tools like superset_chart_get (which likely fetches metadata) and superset_chart_data (which requires manual query construction).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'works only if the chart was saved with query_context' and provides the alternative: 'use superset_chart_data with a manually constructed query'. This is clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the function list is engine-specific and represents available functions in the connected database, which is useful behavioral context beyond the schema. It doesn't discuss pagination or error cases, but for a simple read-only list operation the disclosure is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus an args block, front-loaded with the main purpose. Every sentence adds value, and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, an output schema (so return details are not required), and the description covers primary function and use case. It is complete enough 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must clarify the parameter. It does so by stating 'database_id: Database connection ID', which explains the identifier's role. Since this is the only parameter, the description fully compensates for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource as 'available SQL functions in the database', clearly distinguishing it from sibling tools like superset_database_tables and superset_database_schemas. It is precise 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the tool is 'Useful for building SQL queries with engine-specific functions', providing a clear when-to-use context. It doesn't name alternatives, but the use case is specific enough for an agent to choose this over other database introspection 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?
With no annotations, the description carries the full burden and explains key behaviors: reports send scheduled screenshots, alerts trigger on non-empty SQL results, and recipients follow a specific JSON format. It lacks explicit mention of permissions, return values, or error handling, but the operational behavior is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear summary, separated report/alert guidance, and a readable Args list. It's slightly verbose but every section adds value with examples and clarifications.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 9-parameter schema with no descriptions, the description is quite complete and covers all parameters. Minor gaps include not explicitly stating conditional requirements (e.g., dashboard or chart required for Report, database and sql for Alert) and not mentioning response/return value, but the provided information is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter with examples (crontab formats, recipients JSON structure, SQL condition semantics). It adds meaning beyond the schema's raw types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Create a report or alert') and distinguishes between the two modes, which differentiates it from sibling tools like update/delete. It also explains the resource types and their purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use Report vs Alert ('For Report: specify dashboard or chart' / 'For Alert: specify database and sql'), which guides parameter selection. It does not explicitly name alternative tools or state when not to use it, but the distinction 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?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains that get_all fetches ALL records and ignores page/page_size, defines page as starting from 0, caps page_size at 100, and provides a RISON filter example. This goes beyond a simple 'list' statement, though it could still mention auth implications or return format (the latter is covered by an output schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a short list of standard roles, then a labeled 'Args' section covering each parameter. Every sentence contributes practical information, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool, this description is comprehensive: it states the purpose, helps identify typical roles, explains pagination and filtering, and clarifies the get_all behavior. An output schema exists to describe the return structure, so the description does not need to duplicate that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining every parameter: page, page_size, q (with a concrete RISON example), and get_all (with its behavior). This adds meaningful semantics beyond the bare schema fields and their defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the list of Superset roles' — a specific verb+resource combination. Listing standard roles (Admin, Alpha, Gamma, sql_lab, Public) adds useful context and implicitly distinguishes this list operation from sibling tools like superset_role_get, superset_role_update, and superset_role_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides solid usage context for parameters (pagination, max page_size, get_all behavior) and a filter example, but it does not explicitly mention alternatives or exclusions (e.g., 'for a single role, use superset_role_get'). The intended use is implied rather than explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses pagination behavior, max page size, and the get_all flag, but does not explicitly state that this is a read-only operation or mention any authentication requirements or side effects. The examples for RISON filters add useful behavioral context, but deeper transparency is lacking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear lead sentence followed by a detailed args section. Each sentence provides necessary information, with no wasted words. The RISON examples are concise yet critical for usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, pagination, RISON filters), the description covers everything needed for correct invocation. The output schema exists, so return values need not be explained. The description is sufficient even without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates. It explains every parameter: page, page_size, q, and get_all, including max values and RISON examples. This gives the agent complete understanding of how to craft queries.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the list of Superset users' with a specific verb and resource. It distinguishes itself from sibling tools like superset_user_get by focusing on listing multiple users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool (listing users with optional filters), but does not explicitly mention alternatives or when not to use it. No exclusions are stated, but the pagination and filter examples imply typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It explains that annotations appear as vertical lines/areas on time-series charts and provides a specific behavioral guideline for point-in-time events (set start_dttm = end_dttm). It does not mention permissions, prerequisites, or return values, but the presence of an output schema reduces the need to describe return types.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized: a one-sentence purpose, a brief context sentence about chart display, and a structured Args block. Every sentence adds value, with no redundancy or filler. The front-loaded purpose ensures quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, all parameter semantics, and important behavioral notes, making it highly informative. The existence of an output schema means return values don't need to be explained. The only gap is the lack of explicit mention of prerequisites like the layer needing to exist, but this is a minor omission given the overall thoroughness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, but the description fully compensates by explaining every parameter. It specifies the source for annotation_layer_id, provides ISO format examples for start_dttm and end_dttm, clarifies the optionality of long_descr and json_metadata, and even offers guidance on point-in-time events. This goes well beyond the schema's basic type information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'annotation (timeline event) in the specified layer,' making it unambiguous. It distinguishes from sibling tools like annotation_layer_create by emphasizing 'in the specified layer' and from annotation_update/delete by the create action. The additional context about vertical lines/areas on charts reinforces its specific purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what the tool does and why annotations are used, which implies when to use it. However, it does not explicitly mention alternatives or exclusions, such as when to use annotation_layer_create or annotation_update instead. Despite this, the purpose is self-evident, and the sibling list offers enough disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains pagination behavior and that get_all overrides page/page_size, which is useful. It does not outline authentication requirements or rate limits, but these are less relevant for a simple read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The extra explanation about annotation layers and parameter details is valuable without being verbose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists, and the description covers key behaviors and parameter semantics. It could mention sorting or filtering options, but for a basic list tool with three simple params, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, but the description compensates fully by explaining each parameter: page starts at 0, page_size max 100, get_all ignores pagination. This adds significant meaning beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List annotation layers' with a specific verb and resource, and clarifies that an annotation layer is a container for annotations, effectively distinguishing it from the sibling tool superset_annotation_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on what an annotation layer is and how to use the pagination parameters, but does not explicitly mention alternatives or exclusion criteria. The distinction from annotation_list is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the output format (ZIP, base64-encoded), the included asset types, and that database passwords are excluded. It does not explicitly state whether the operation is read-only, but 'export' inherently implies no mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear top-line purpose, a list of contents, and a structured return format. Every sentence provides value, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, all-assets export tool, the description is fully complete. It explains what is included (dashboards, charts, datasets, connections), what is excluded (passwords), and the exact JSON response shape. The output schema further confirms this completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing to clarify. The description adds meaningful context about the return value (format, encoding, data, size_bytes), which is useful beyond the empty schema. Baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports ALL Superset assets into a single ZIP file, specifying a distinct verb ('Export') and resource ('ALL Superset assets'). This differentiates it from sibling export tools that target individual asset types (e.g., superset_dashboard_export, superset_chart_export).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'Useful for backup or migration between instances.' It does not explicitly mention when not to use or contrast with alternatives, but the emphasis on 'ALL' and the list of included asset types makes the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses key behaviors: that omitting user_ids removes the role from ALL users who have it, that exclude_admin defaults to True to protect admins, and that confirm must be True to apply, with False as a dry-run. This provides meaningful safety and scope context beyond the basic 'remove' action, though it stops short of warning about irreversibility or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The one-line summary is followed by a clean Args list. Every element provides necessary information without fluff, and the dry-run/confirm distinction is communicated in two short lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a bulk operation with a potentially sweeping effect (all users), the description covers the most critical context: the all-users behavior, admin exclusion, and the dry-run safeguard. An output schema exists, so return values are covered. However, it does not address required permissions or whether the operation is reversible, which are notable gaps for a destructive bulk action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does by explaining each parameter: role_id (what to remove), user_ids (explicit list or None to mean all), exclude_admin (skip admins), and confirm (apply vs. dry-run). This adds significant meaning beyond the schema's raw types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Remove a role from multiple users', which is a specific verb (Remove), resource (role), and scope (from multiple users). This clearly distinguishes it from sibling tools like superset_bulk_user_role_add and superset_role_delete, covering both the operation type and the multi-user target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the core usage semantics: how user_ids (explicit list vs. all users), exclude_admin (default skip), and confirm (dry-run vs. apply) affect behavior. It does not explicitly name alternative tools, but the parameter-level guidance is strong enough to infer when to use this tool over a single-user role removal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the order of operations ('Adds new_role_id first, then removes old_role_id') and the safety mechanism (dry-run via confirm flag). This is transparent for a bulk mutation tool, though it omits potential error conditions or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence purpose, a note about the safe two-step behavior, and a clear Args block. Every sentence adds value, 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/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (bulk role replacement with 4 parameters, no annotations, no schema descriptions), the description covers purpose, behavior, and parameter semantics well. It also explains the dry-run feature and admin exclusion. It doesn't mention return values or edge cases, but an output schema exists, and overall the description is sufficiently complete for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), so the description must compensate. It does so effectively by listing each parameter with a clear explanation (e.g., 'confirm: True to apply. False for dry-run'). This is a strong compensation for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a bulk role replacement: 'Replace one role with another for all users who have it.' This uses a specific verb+resource+scope and distinguishes it from sibling tools like superset_bulk_user_role_add and superset_bulk_user_role_remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when replacing a role across all users) and explains the two-step order, but it does not explicitly name alternatives or state when not to use it. It provides clear context without exclusions, so it exceeds a baseline but stops short of full comparative 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?
With no annotations provided, the description carries the full burden. It clearly indicates a non-mutating read operation via 'List' and 'Returns available engines', which is sufficiently transparent for a zero-parameter, read-only tool. It does not overpromise or hide 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, all informative. The action is front-loaded ('List supported database engine types'), followed by return examples and a usage hint. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, zero parameters, and presence of an output schema, the description fully covers what it does, what it returns, and when to use it. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so baseline is 4. The description adds nothing about parameters, but none are needed. Schema coverage is 100% and the empty schema is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'List supported database engine types for creating connections.' It clearly distinguishes this from sibling database tools by focusing on engine types rather than databases themselves, and includes concrete examples (PostgreSQL, MySQL, SQLite).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states its use case: 'Useful for selecting an engine when creating a new connection.' This gives clear context for when to use it, though it does not mention alternative tools 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?
No annotations are present, so the description carries the full burden of disclosing behavior. The verb 'Get' and the phrase 'understand what will break' clearly convey a read-only analysis operation without side effects. It doesn't explicitly state 'read-only', but the intent is unambiguous and it adds contextual value beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely tight: two sentences plus a one-line arg doc. It front-loads purpose, then adds a practical use case, then documents the parameter. No filler or redundant content, while still including all essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with an output schema, the description fully covers what the tool does, why it is useful, and how the parameter is used. It doesn't need to explain return values as the output schema presumably handles that. The mention of datasets and charts gives sufficient preview of the result scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description compensates by documenting the only parameter ('database_id: Database connection ID.'). This gives the agent necessary semantic meaning for the integer type, though it is minimal and doesn't elaborate on formatting or defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'Get' with a clear resource ('objects related to a database connection') and explicitly enumerates the object types (datasets, charts). It also states the operational context ('before deleting a connection'), making the tool's purpose distinct from sibling tools like database_get or database_tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a concrete usage scenario ('Useful before deleting a connection to understand what will break'), which clearly indicates when to invoke it. It does not explicitly mention alternatives or when not to use it, so it falls short of a full 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?
No annotations are provided, so the description carries the burden. It discloses a critical behavioral consequence: 'changing the URI breaks all datasets and charts using this connection.' It also highlights that confirm_uri_change is REQUIRED when changing sqlalchemy_uri. These are valuable transparency details beyond the basic update operation, though it doesn't cover other potential side effects like permissions or irreversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured as a clean docstring with an initial summary and a flat list of parameters. It is longer than a one-liner but every line serves a purpose—parameter explanations and critical warnings. The front-loaded main sentence makes the tool's purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having zero schema coverage, the description fully covers all 9 parameters, including the special verification flag. It also explains the severe impact of URI changes and confirms the minimal required input (database_id). Since an output schema exists, return-value details are not needed. The tool is complex, and this description provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates fully. It provides meaningful explanations for all nine parameters, including pragmatic details like 'Whether to show in SQL Lab' and 'Allow CREATE TABLE AS SELECT.' The critical warning about sqlalchemy_uri and the requirement for confirm_uri_change add significant semantic value beyond the raw schema field names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb-action sentence: 'Update a database connection.' It explicitly names the resource and the operation, and adds scope with 'Pass only the fields you want to change.' This differentiates it from sibling tools like create, delete, and get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need to modify an existing database connection, and it requires database_id. It doesn't explicitly mention alternatives or exclusions, but the context and required parameter make the usage unambiguous. It also instructs to pass only changed fields, which is a practical usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that SQL is not executed, and it discloses the engine-support limitation. However, it does not describe error behavior for unsupported engines, authentication needs, or other potential side effects, so the transparency is good but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise: a one-sentence purpose, a brief IMPORTANT caution, and a compact Args list. Every sentence earns its place, and the most critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with three parameters and an existing output schema, the description covers the core purpose, parameter semantics, and a key compatibility caveat. It does not explain the exact return format or error handling, but the output schema likely covers the return value, making this adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only types and no descriptions for database_id, sql, or schema. The description compensates fully by listing each parameter with a clear meaning (e.g., 'Database connection ID', 'SQL query to validate', 'Schema for validation context') and even includes an example value for schema. This adds critical meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action: 'Validate SQL query syntax without executing it (EXPLAIN-like check).' This clearly identifies what the tool does and distinguishes it from sibling tools like superset_sqllab_execute (which executes) and superset_database_validate_parameters (which validates connection parameters).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by stating the tool validates without executing and explicitly warns that not all database engines support SQL validation (with PostgreSQL cited as supporting). This implies when to use it, but it does not explicitly name alternative tools or provide concrete when-not-to-use exclusions beyond the engine caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden. It discloses key behaviors: existing datasets are returned, missing ones create a physical dataset, schema_name defaults to DB schema, and it returns a JSON string. However, it does not mention potential side effects (e.g., schema refresh), error conditions, or permission requirements, leaving minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a one-line summary, behavior explanation, Args list, and Returns section. Every sentence contributes useful information without repetition or fluff, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: purpose, behavioral logic, all parameters, and return value. Since an output schema exists (per context signals), its absence in the description is acceptable. The main missing piece is error handling and edge cases (e.g., what happens if the table doesn't exist), but for moderate complexity this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly covers all three parameters with meaningful context: database_id is tied to superset_database_list, table_name is clearly the table in the database, and schema_name includes examples and default behavior. This fully compensates for the 0% schema description coverage, adding value beyond the raw JSON schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Get an existing dataset or create a new one for a table,' which clearly states the verb, resource, and the get-or-create logic. This distinguishes it from sibling tools like superset_dataset_get and superset_dataset_create, which would only perform one side of this operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that if a dataset for the table already exists it returns it, otherwise creates a new physical dataset. This clearly implies an idempotent 'ensure exists' use case, but it stops short of explicitly naming alternatives or providing when-not-to-use guidance. The context is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides important behavioral details: pagination starting at page 0, a maximum page_size of 100, and automatic pagination for get_all. It also gives a concrete RISON filter example. The read-only nature is implied by 'List' but not stated explicitly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, brief domain context, and a clean parameter list. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema, the description covers the essential usage and parameter semantics. It does not explicitly mention authentication or read-only status, but for a list operation this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are explained with meaningful semantics beyond the schema, including a RISON filter example for q. Since schema coverage is 0%, this fully compensates for the lack of structured descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List Superset user groups' with a specific verb and resource. It also explains that a group combines users and roles, which distinguishes this from related tools like superset_group_get or superset_group_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool, including pagination options and the get_all flag for fetching all records. It does not explicitly name alternative endpoints, but the purpose and usage are unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses pagination behavior, page_size max (100), RISON filter syntax with examples, and get_all automatic pagination overriding page/page_size. It does not mention auth or permission requirements, but for a read-only list tool, the essential behavioral traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loads the main purpose in one sentence, and uses well-structured 'Args' bullet points with minimal fluff. Every line earns its place, providing maximum information in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, output schema exists), the description covers pagination, filtering, and get_all behavior thoroughly. It does not describe the return format, but the output schema likely handles that. It could briefly mention that this is for query history vs. saved queries, but the main sentence already implies it. Overall, adequate for a filtered-list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates by explaining every parameter: page (number), page_size (records per page, max 100), q (RISON filter with concrete examples for status and database), and get_all (ignores page/page_size). This is far richer than the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve the history of executed SQL queries' uses a specific verb (retrieve) and resource (history of executed SQL queries), clearly distinguishing it from sibling tools like superset_query_get (single query) and superset_saved_query_list (saved queries). The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool (to list executed query history) and provides usage details like pagination and filtering. It does not explicitly exclude alternatives or name sibling tools for comparison, but the scope is clear from the 'history of executed SQL queries' phrase.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses that it is a partial update ('Pass only the fields to change') and highlights a critical behavior: 'recipients: JSON string with new recipient list (REPLACES all current recipients).' It also explains the meaning of 'active.' It does not mention permissions or error handling, but the provided behavioral details go beyond a simple update statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core action. The Args list is organized and contains only necessary information, with no redundant filler or tangential content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers all parameters and key behavioral semantics (partial update, recipient replacement). An output schema is present, so return values need no explanation. It could add explicit notes about omitted fields remaining unchanged, but 'Pass only the fields to change' already implies that, making it sufficiently complete for an update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates fully by explaining each parameter in the Args list. It provides a concrete cron example, clarifies active as enable/disable, and defines recipients with a warning about replacement. This exceeds what the plain schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Update a report/alert,' a specific verb+resource statement that clearly distinguishes it from sibling tools like superset_report_create, superset_report_get, and superset_report_delete. It also adds 'Pass only the fields to change,' which conveys the partial-update nature of the tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context by stating this is for updating an existing report/alert and clarifies that only the fields needing changes should be passed. However, it does not explicitly name alternatives or state when not to use this tool, though the sibling list makes the distinction obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses return types, the semantics of the tags parameter, and notably that get_all ignores page/page_size for automatic pagination. This adds useful behavioral context beyond the schema, though it could mention permissions or error conditions but that's not critical for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with a one-line purpose followed by a bulleted Args section. Every sentence adds value, and the main action is front-loaded. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (so return values are inferred), the description covers the key aspects: purpose, object types, and parameter behavior. It doesn't elaborate on permission requirements or edge cases, but for a straightforward tag-query tool with 4 optional parameters, it is sufficiently complete. A 5 would require more explicit guidance on pagination trade-offs or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), so the description fully compensates with a clear Args section. It explains tags as comma-separated, page starting at 0, page_size max of 100, and get_all overriding pagination. This adds substantial meaning beyond the schema's types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and the resource (objects tagged with specified tags), and explicitly lists the object types returned (dashboards, charts, datasets, queries). This distinguishes it from tag management tools like superset_tag_get or superset_tag_list, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you need objects based on tags. It also explains the default behavior (if tags not specified, returns all tagged objects) and the effect of get_all. However, it does not explicitly mention alternatives or exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavior: page numbering starts at 0, page_size max 100, and get_all fetches all records ignoring page/page_size. This goes beyond the schema, which only has type/default. It doesn't cover error handling or return format, but output schema covers that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact docstring with an Args section. Each sentence provides distinct, necessary information with no filler. It is front-loaded with the one-line summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward list operation with an output schema present. The description covers all parameters and the pagination behavior, and references the layer list for IDs. No critical gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains all four parameters with useful semantics: the source of annotation_layer_id, page starting at 0, page_size max 100, and get_all ignoring pagination. This adds meaning beyond the schema's bare types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and resource 'annotations' with a clear scope: 'in the specified layer'. This distinguishes it from sibling tools like superset_annotation_get (single annotation) and superset_annotation_layer_list (layers).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states 'annotation_layer_id (from annotation_layer_list)', which tells the agent where to obtain a needed prerequisite. It also explains the get_all option versus pagination, clarifying when to use which. However, it does not explicitly name alternatives like 'use superset_annotation_get to fetch a single annotation'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the non-removal of existing roles, the selection logic, the exclude_admin default, and the dry-run behavior. It does not disclose edge cases like idempotency (what happens if a user already has the role), but the core behavior is transparent enough for an agent to safely invoke the 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with a clear one-sentence purpose, then uses an Args list to describe parameters without redundancy. Every sentence contributes value, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, two selection modes, dry-run option), the description covers all essential guidance. The presence of an output schema means return-value details are not needed in the description. An agent has enough information to select and invoke this tool correctly, including how to avoid unintended modifications via the confirm flag.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does so by explaining every parameter (role_id, user_ids, filter_role_id, exclude_admin, confirm) and their interdependencies, including the relationship between user_ids and filter_role_id. This adds substantial meaning beyond the bare input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific verb and resource: "Add a role to multiple users." It also distinguishes from sibling tools by noting "without removing existing roles," which sets it apart from superset_bulk_user_role_remove and superset_bulk_user_role_replace. The purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it explains the two selection modes (explicit user IDs vs. current role filter), notes that filter_role_id is ignored when user_ids is set, and mentions the dry-run capability via confirm. It implies when to use this tool (additive role changes) but does not explicitly contrast with alternative tools. Still, the guidance is practical and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses pagination behavior, the get_all automatic pagination that ignores page/page_size, and the role of the q parameter with RISON filter examples. It does not explicitly state read-only nature or error/rate-limit behavior, but the 'List' verb and the lookup-focused guidance cover the core behavioral traits adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a brief purpose line, a high-priority usage note, and a clearly formatted parameter list with examples. Every sentence adds value, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's complexity is moderate (pagination, filtering, get_all), and the description covers these aspects thoroughly. Since an output schema exists, it doesn't need to explain return values. The prerequisite guidance and parameter examples make it complete for an agent to select and use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully with a dedicated Args section. Each parameter (page, page_size, q, get_all) is explained, and the q parameter includes concrete RISON examples for filtering by name, type, and dataset. This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List Superset charts with pagination,' which clearly identifies the verb (list), resource (Superset charts), and scope (with pagination). It also distinguishes itself from sibling tools by noting it should be called before chart_get/chart_delete to look up chart IDs, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'IMPORTANT: always call this tool before chart_get/chart_delete' instruction, which gives a clear when-to-use directive and a specific workflow context. However, it does not mention when not to use it or alternative tools for different scenarios, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses a critical side effect: specifying roles automatically syncs datasource_access to all dashboard datasets. It also notes the published default (draft) and role semantics, which goes beyond a simple 'create' action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with a summary sentence, an IMPORTANT note, and an Args list. Every line adds information without filler, making it both concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All 7 parameters are covered with practical details, including the important role-sync behavior. Since an output schema exists, the lack of return-value explanation is acceptable. This is a complete description for a moderately complex create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates. Each argument is explained with its purpose (e.g., slug uniqueness, json_metadata contents, roles semantics including empty list = all users). This adds significant meaning beyond the bare schema types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new dashboard,' a specific verb and resource. This clearly differentiates it from sibling tools like superset_dashboard_update, superset_dashboard_publish, and superset_dashboard_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is explicit: create a new dashboard. This implies when to use it versus other dashboard-related tools, but it does not explicitly name alternatives or state when not to use it, so it lacks full exclusionary 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?
With no annotations, the description carries the full burden and does disclose key behavioral traits: output is a base64-encoded ZIP, includes all dependencies, and can be re-imported. This is transparent about the return format and scope, though it does not mention permissions or size limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-structured, leading with a one-sentence summary, then a brief note on importability, followed by Args and Returns sections. No unnecessary words or duplication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and the fact that an output schema is described inline, the description covers input, output format, dependencies, and reuse path. It is complete for a straightforward export tool, with no required missing details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'dashboard_ids' is described with a concrete format (comma-separated IDs) and an example, compensating fully for the schema's lack of description. This is beyond what the raw 'string' type provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Export' plus resource 'dashboards' and clearly scopes the action to include dependencies (charts, datasets, databases). It distinguishes from similar tools like superset_dashboard_get or superset_assets_export by highlighting the ZIP export and import compatibility.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this tool is for exporting dashboards for reuse via superset_dashboard_import, establishing a primary use case. It does not explicitly mention alternatives or exclude cases, but the context is sufficient for basic selection among dashboard-related siblings.
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?
With no annotations provided, the description carries the full burden, and it excels: it enumerates the five automatic steps, explains how existing permissions are checked, warns about RLS rules, and clearly describes the dry-run vs. apply behavior controlled by confirm_grant. This gives the agent a strong understanding of side effects and safeguards.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead sentence, a numbered list of automatic actions, and an Args section. It is somewhat verbose for the numbered steps, but each step earns its place by explaining the tool's internal logic, which is valuable for the agent. Overall, it is not excessively long and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description is remarkably complete. It covers the full workflow, the confirmation/dry-run mechanism, and the RLS warning—topics an agent needs to invoke the tool safely. An output schema exists, so the absence of return-value details is acceptable. No critical gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains dashboard_id and role_id with source hints (from dashboard_list/role_list) and clarifies confirm_grant as 'True to apply changes. False for dry-run only.' This goes beyond the raw parameter names and types, though it could provide even more detail about expected formats or lookup methods.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Grant a role access to a dashboard by automatically finding all dashboard datasets and adding datasource_access to the role's permissions.' This clearly distinguishes it from siblings like superset_dashboard_revoke_role_access and superset_role_permission_add by emphasizing automatic dataset discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by explaining the automated workflow and the dry-run behavior via confirm_grant, and mentions where to obtain IDs ('from dashboard_list', 'from role_list'). However, it does not explicitly state when to prefer this tool over alternatives like directly adding permissions with superset_role_permission_add, so no exclusionary guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses the key behavioral trait of potential cross-dashboard breakage, the warning check, and the dry-run behavior without confirm_revoke=True. This is strong transparency, though it does not cover error handling or auth requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficient: a clear action statement, a prominently marked IMPORTANT warning, a brief dry-run explanation, and a concise Args list. Every sentence contributes information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (destructive mutation with cross-dashboard side effects and a dry-run mode), the description covers the critical context: the side-effect mechanism, the confirmation parameter, and parameter provenance. The presence of an output schema reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining each parameter's meaning and source ('from dashboard_list', 'from role_list') and the effect of confirm_revoke (True=apply, False=dry-run). This adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Revoke a role's access to a dashboard') and the mechanism ('removing datasource_access for the dashboard's datasets'), making it distinct from its sibling grant_role_access and other permission tools. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context, explaining the destructive side effect on other dashboards sharing the same dataset and instructing that the tool checks/warns about this. It also clarifies the dry-run vs. apply workflow using confirm_revoke. However, it does not explicitly name alternatives or when-not-to-use conditions beyond the shared-dataset warning.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that creation triggers a validation attempt and that the URI must be reachable from the server side—a non-obvious and important behavioral trait. However, it does not mention permission requirements or failure behavior, though the validation note adds significant transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-sentence purpose, a highlighted critical warning, and a labeled Args section. It is efficient and front-loaded with the most important caveat, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all 8 parameters, their defaults, and the critical validation behavior. Since an output schema exists, the absence of return-value details is not a gap. For a create tool with this complexity, the description is thorough and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite the schema having 0% property descriptions, the description lists and explains every parameter, including examples for sqlalchemy_uri and a note that extra is a JSON string with engine_params and metadata_params. This fully compensates for the bare schema and adds meaningful context beyond the type/default information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Create a new database connection,' which clearly identifies the action (create) and the resource (database connection). This distinguishes it from sibling tools like superset_database_test_connection, superset_database_update, and superset_database_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The IMPORTANT note about Superset validating database availability on creation provides key usage context, advising that the URI must be reachable from the Superset server. This implies the tool is appropriate when a reachable URI is available, but it does not explicitly reference alternative tools or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden. It discloses exactly what metadata is returned (columns, types, indexes, primary keys) and notes the default schema behavior, giving the agent a concrete picture of the operation. It does not cover error cases or permissions, but the read-only nature is evident from 'Get' and the described outputs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first clause states the purpose, the second sentence gives the use case, and the Args list is minimal and scannable. Every sentence earns its place without repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. It provides all essential context for correct invocation: what the tool does, when to use it, and what each parameter means. The schema default behavior is also clarified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the structured schema has 0% description coverage, the description's Args section explains each parameter in plain language, including database_id, table_name, and schema_name. It adds important context like 'If not specified, uses the default schema', fully compensating for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Get') and a concrete resource ('table metadata'), explicitly listing columns, data types, indexes, and primary keys. This clearly distinguishes it from sibling tools like superset_database_tables (listing tables) or superset_database_select_star (previewing rows).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'Useful for understanding table structure before writing SQL queries' provides clear context for when to use this tool. It does not explicitly name alternatives or exclusions, but the guidance is sufficient for an AI agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the physical/virtual dual behavior, explains schema default behavior, and states the return format. It omits permission requirements and error scenarios but provides more than minimal 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an intro, parameter list, and return type. Every sentence contributes meaning, with no fluff or repetition. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the physical/virtual distinction and the availability of an output schema, the description covers the tool's purpose, parameter usage, and return format. It is complete enough for an agent to select and invoke the tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter's meaning and role: table_name, database, schema_name (with default), and sql (for virtual). This adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new dataset, distinguishes between physical and virtual datasets with specific definitions, and differentiates it from sibling tools like update/delete/get by focusing on the create 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use physical vs virtual datasets and references superset_database_list for database IDs, providing clear usage context. However, it does not explicitly name alternative tools like superset_dataset_get_or_create or state 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains pagination behavior, that get_all fetches all records and ignores page/page_size, and that it returns a JSON string. It also provides RISON filter syntax examples, which adds useful behavioral context. It does not mention potential errors, rate limits, or authentication, but the core behaviors are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise, with an introduction, definition, important note, Args section with examples, and Returns line. Every sentence adds value, and the formatting makes it easy to scan. It avoids redundancy with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description does not need to explain return structure, but it still covers key aspects: pagination, filtering, get_all mode, and its role relative to dataset_get. It is comprehensive for a list operation and provides enough context for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description has an explicit 'Args' section explaining each parameter in detail: page starts at 0, page_size max 100, q uses RISON with concrete examples, and get_all overrides pagination. This adds substantial meaning beyond the schema's basic type/default information and fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Superset datasets with pagination, defines what a dataset is, and explicitly distinguishes it from dataset_get by saying to call this first to discover current IDs. This is a specific verb+resource with clear sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance by stating 'IMPORTANT: always call before dataset_get to discover current IDs', giving a clear when-to-use context. It also includes detailed filtering examples for searching by name, schema, and database, which implies practical use cases. However, it does not explicitly mention when not to use this tool in favor of other alternatives beyond dataset_get.
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 the read-modify-write pattern: 'fetches current group users, merges in new ones, and updates the group.' This is key behavioral context beyond the simple 'Add users' phrasing. It doesn't mention error cases or idempotency, but for a tool with no annotations, it carries the burden well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs, with a clear Args list. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple two-parameter interface, the description explains the purpose, the merge behavior, and the parameters. An output schema exists, so return format is covered. No critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides explicit parameter meanings: 'group_id: Group ID' and 'user_ids: List of user IDs to add.' This fully compensates for the schema's lack of description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what it does: 'Add users to a group without removing existing ones.' This clearly distinguishes it from superset_group_remove_users and other group-related tools, using a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the convenience behavior (fetches, merges, updates) and implies it's an additive operation. It doesn't explicitly name alternatives, but the tool name and context provide enough differentiation. Could mention when to use this instead of group_update, but not necessary.
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?
With no annotations, the description carries full responsibility and excels: it explicitly warns that roles and users REPLACE entire lists rather than append, and highlights the required confirmation flags. This is critical behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with the core purpose, and uses clear sections for important caveats and parameter explanations. Each sentence contributes, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tricky partial-update and list-replacement behavior. It explains the complete usage pattern, including prerequisites for adding items. Given the presence of an output schema, no return-value explanation is needed, and the context is sufficient for an agent to operate correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description's Args section is essential. It explains every parameter's meaning, clarifies the replace behavior for roles/users, and specifies when confirmations are required—adding significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a group' with a specific verb and resource, followed by supported fields. It is distinct from the group_add/remove tools but does not explicitly differentiate itself from sibling tools like superset_group_add_users, relying on the tool name for distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage guidance: 'Only pass the fields you want to change' and warns about replacement semantics for roles/users. It even outlines a workflow for adding a single role/user via group_get, though it does not mention the alternative dedicated tools (group_add_users/roles).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. The verb 'Get' implies a read-only operation, and the description notes the prerequisite of calling the list tool first, but it does not explicitly confirm read-only safety, permissions, or error behavior. This is a basic but acceptable disclosure for a simple retrieval 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the purpose, and includes an important usage note and parameter explanation in three short sentences. Every sentence adds value without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single parameter, clear usage guidance, and the presence of an output schema, the description adequately covers the essentials. It explains what the tool does, when to use it, and exactly how to obtain the required ID. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the only parameter report_id as 'Report ID (integer from report_list result)', providing clear meaning and source beyond the schema's bare integer type. This fully compensates for the schema's lack of a description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'detailed information about a report/alert by ID', making the tool's function unambiguous. It clearly distinguishes from sibling tools like superset_report_list (listing) and superset_report_create/update/delete (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'if the ID is unknown, call superset_report_list first', providing a clear when-to-use directive and naming the alternative tool. This directly guides the agent on the correct invocation sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that RLS adds a WHERE clause, explains the impact of filter_type, and provides clause syntax and examples. It does not cover potential error conditions or permission requirements, but for a create operation the disclosed behavior is substantive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a clear one-line purpose, a brief functional explanation, and a well-organized Args list with examples. Every sentence adds value, and the length is appropriate given the need to document parameters that the schema leaves undescribed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 7 parameters and no schema descriptions, the tool description provides complete parameter documentation, contextual guidance (e.g., how to obtain dataset/role IDs), and behavioral explanation of RLS and filter types. The presence of an output schema means return values need not be explained, and no prerequisites are missing for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description fully documents all 7 parameters in the Args section, including examples for clause, allowed values for filter_type, and source hints for tables and roles (from dataset_list, role_list). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with 'Create a Row Level Security rule'—a specific verb and resource—and goes further to explain the rule's function (adding a WHERE clause to queries). This clearly distinguishes it from sibling tools like superset_rls_update or superset_rls_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the context of RLS behavior and the distinction between 'Regular' and 'Base' filter types, helping users decide when to use each. It also references dataset_list and role_list for obtaining IDs. However, it does not explicitly mention alternatives or exclusions (e.g., 'use superset_rls_update to modify existing rules'), leaving some implicit 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?
With no annotations, the description carries the full burden. It discloses that existing permissions will be REPLACED, which is the critical destructive trait, and explains the confirm parameter as a dry-run vs apply toggle. It does not mention auth requirements or rate limits, but the main risk is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a bulleted arg list. All key information is front-loaded, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and an existing output schema, the description covers the purpose, parameter roles, destructive replacement behavior, and the confirm/dry-run mechanism. It is complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains every parameter meaning: source_role_id, target_role_id, and confirm, including the critical dry-run/apply semantics. This fully compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Copy all permissions from one role to another' and explicitly notes 'full replacement'. This clearly states what the tool does and distinguishes it from sibling tools like superset_role_permission_add or superset_role_update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates the operation's scope and the replacement semantics, making it clear when to use this tool over granular permission tools. However, it does not explicitly name alternative tools or state when not to use it, so it misses the explicit exclusion 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?
With no annotations, the description carries the full burden of behavioral disclosure. It provides a critical behavioral detail: the name field is required even if unchanged, and omitting it causes Superset to return a 500 error. This is valuable beyond the schema, though it does not mention permissions or response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a one-sentence purpose, a clearly highlighted IMPORTANT caveat, and a simple args list. Every element earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 3-parameter update tool, this description is complete: it covers all parameters, highlights the critical required-name quirk, and notes the failure mode. The presence of an output schema further reduces the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining each parameter: tag_id is the target ID, name is required even if unchanged, and description is optional. It adds meaningful version-specific insight (Superset 6.0.1 required name) that the schema alone cannot convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Update a tag (rename or change description).' This clearly states the tool's function and distinguishes it from sibling tools like superset_tag_create, superset_tag_delete, and superset_tag_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates usage for updating existing tags (rename or change description). It does not explicitly mention alternatives or exclusions, but the verb and scope are sufficiently clear that an agent would know when to select this tool over create/delete/list siblings.
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?
With no annotations provided, the description carries the full transparency burden, and it excels: it discloses the 'not registered' error for deprecated viz types, warns that moment.js date formats render as literal text, explains that big_number_total fonts can cause scrolling, and notes that country_map tooltips are clipped unless CSS is applied. It also clarifies that query_context is required for chart_get_data to work, which is a non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long, but well-structured into clearly labeled sections (Args, IMPORTANT, CRITICAL, REFERENCE parameters, etc.) and front-loaded with the core purpose. It could be trimmed—CSS recommendations and the exact deprecation list are arguably extra—but the density of actionable information is high and the structure keeps it scannable, so it earns a high but not perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's complexity and lack of annotations, the description covers all seven parameters, includes error-prone edge cases, provides exact format examples, and explains prerequisites like datasource_id and query_context. Since an output schema exists, not detailing return values is acceptable, and the description is otherwise comprehensive enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must fully compensate, and it does. It explains viz_type with a complete list of valid values and deprecated aliases, datasource_id origin, datasource_type default, params as a JSON string with detailed formatting requirements, query_context's role, and dashboards as a list of IDs. This adds immense meaning beyond the bare schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb-object statement 'Create a new chart,' which precisely identifies the action and resource. It also enumerates the chart types and parameters, making it clear this is the creation tool and not an update, delete, or copy operation among the chart-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it lists required arguments, tells the agent to pull datasource_id from superset_dataset_list, and warns against deprecated viz_type values that will error. It does not explicitly mention alternatives like superset_chart_update for modifications or superset_chart_get for reads, so it falls short of full when/when-not coverage, but the creation-specific guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well by disclosing the exact JSON structure, a critical gotcha about time_range being at the query level, and allowed time_range values. It does not explicitly state read-only behavior, but 'retrieve data' implies it. The detailed format and constraint notes add valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long due to the necessary JSON example, but it is well-structured: purpose, alternative, then args. Every element earns its place—the format and allowed values are essential. It is not bloated, just slightly verbose given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one complex JSON parameter and an output schema present, the description is remarkably complete. It covers the query building blocks, the datasource specification, result format, and the critical time_range placement. The existence of an output schema means return values need no further detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter query_context has zero schema description coverage, so the description fully compensates by providing a complete JSON template with datasource, queries, columns, metrics, filters, orderby, row_limit, time_range, result_format, and result_type. It also lists allowed time_range values and an important formatting rule.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Execute an arbitrary query against a dataset and retrieve data.' It explicitly distinguishes itself from the sibling tool by stating 'To get data from an existing chart, use chart_get_data instead.' This makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is explicit: 'Allows fetching data directly from a dataset without creating a chart' and names the alternative for existing charts. This tells the agent exactly when to choose this tool over chart_get_data. Although other siblings exist, the most relevant alternative is clearly identified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the 404 error for missing IDs and highlights the prerequisite that IDs come from dashboard_list. While it does not explicitly state read-only behavior, 'Get' implies it, and the presence of an output schema covers return-value details. This is meaningful behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct: three sentences plus an Args line. The main purpose is front-loaded, the important usage note is highlighted with 'IMPORTANT', and every sentence adds value without repetition. Ideal length for a single-parameter getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter GET tool with an output schema, the description covers all essential operational aspects: how to obtain a valid ID, the 404 error behavior, and the core action. It does not need to explain return fields since the output schema exists. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only 'dashboard_id' as an integer with zero description. The description compensates by specifying 'Dashboard ID (integer from dashboard_list result)', clarifying the source and expected format. This fully addresses the missing schema description, though it could add more about the ID's role (e.g., required, no default).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get detailed information about a dashboard by ID.' The verb 'Get' is specific, the resource is a dashboard, and the qualifier 'detailed' distinguishes it from dashboard_list. It is unambiguous and differentiates among siblings by emphasizing ID-based lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'if the ID is unknown, first call superset_dashboard_list to find the desired dashboard.' It also warns about the 404 behavior for non-existent IDs, which informs when not to use the tool directly. This is clear, actionable, and names the alternative tool.
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?
With no annotations provided, the description fully discloses important behaviors: roles/owners are replaced, position_json and json_metadata are fully replaced, datasource_access is auto-synced, CSS is injected as a <style> tag and does not affect Explore view. It even includes detailed side-effect reasoning (overflow formula) and debugging tips, leaving little hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but given 9 parameters and complex side effects, it is well-structured with clear per-parameter sections. The extensive CSS examples could be trimmed without severe loss, but they add concrete value for the agent. The main purpose is front-loaded, and later content is logically organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complexity is high with 9 params, no annotations, and 0% schema coverage. The description fully covers each parameter, side effects, and usage caveats. Although return values aren't described, an output schema exists, so that's not required. The description is complete enough for an agent to invoke the tool correctly and anticipate all important behaviors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description compensates admirably. Every parameter (dashboard_id, dashboard_title, slug, published, json_metadata, css, position_json, owners, roles) is explained with meaning, constraints (slug must be unique), and behavioral consequences (replacement semantics, sync behavior). It even provides example CSS fixes for the css parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an existing dashboard. Pass only the fields to change', clearly identifying the verb (update), resource (dashboard), and scope (existing). It distinguishes itself from siblings like superset_dashboard_create, superset_dashboard_delete, and superset_dashboard_publish by focusing on modifying existing dashboards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool (updating any dashboard attribute) and provides practical guidance: 'Pass only the fields to change', tells users to call dashboard_get before changing position_json, and explains the automatic datasource_access sync when roles change. However, it doesn't explicitly name alternative tools like superset_dashboard_publish for published field changes, but the field-level explanations are sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clarifies the operation is a read-only 'get' and specifies that it returns a JSON string with dataset details. It does not disclose error behavior or permissions, but for a simple getter with this verb, the transparency is reasonable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: one-sentence purpose, an important note about prerequisites, and clearly labeled Args/Returns sections. Each line adds value without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation, the description provides the return format, the prerequisite, and parameter semantics. With an output schema present (though not detailed here) and no complex nested objects, this is sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has one required integer 'dataset_id' with no description. The description adds meaning by specifying it's an integer from the dataset_list result, explaining where to obtain the value. This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('dataset'), explicitly listing what detailed information includes (columns, metrics, SQL). It distinguishes from sibling tool superset_dataset_list by stating 'detailed' and providing the prerequisite of using list first to obtain the ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use this tool: if the ID is unknown, call superset_dataset_list first. This provides a clear prerequisite and implies using this tool only when the ID is known, effectively guiding tool selection.
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?
With no annotations provided, the description carries the full burden and excels: it discloses the destructive behavior of columns replacement, the required confirm_columns_replace gate, the Superset flag reset gotcha, and the recovery path via dataset_refresh_schema. This is precisely the safety-critical context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than a simple one-liner, but every sentence adds value—warnings, formats, and gotchas are included. It is well-structured with clear Args/Returns sections and front-loaded purpose. The only slight detractor is the length, but it is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, complex side effects, and specific edge cases. The description covers every parameter, explains return format, and provides essential operational guidance. Given the rich sibling context and no output schema details in the prompt, this description is complete enough for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully. Each parameter is explained beyond its schema type: columns includes a format example and the critical replacement behavior, metrics includes a format, and always_filter_main_dttm includes detailed semantics about omission and preservation. This far exceeds schema info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb+resource statement: 'Update a dataset.' followed by the usage rule 'Only pass the fields you want to change.' This unambiguously distinguishes it from the create/delete/refresh siblings in the toolset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on how to perform partial updates and includes critical warnings about replacing columns and the always_filter_main_dttm flag. However, it does not explicitly mention alternatives (e.g., 'use superset_dataset_create for new datasets'), though the sibling names make this obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly implies a read-only operation via 'Get' and adds helpful context that the role_id should come from a prior role_list result. It doesn't discuss error behavior, but the simplicity of the operation makes this less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the main purpose, and includes a clear 'IMPORTANT' note and a structured Args section. Every sentence adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with one parameter, the description covers purpose, usage prerequisite, and parameter provenance. The presence of an output schema handles return values, so the description is complete enough 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/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only type 'integer' with no description, so the description compensates by explaining the semantic source: 'Role ID (integer from role_list result).' This adds valuable cross-tool context that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Get role information by ID.' It distinguishes from siblings like superset_role_list (which lists roles) and superset_role_update/delete, making it clear this is the read-by-ID operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: if the ID is unknown, call superset_role_list first. This directly addresses when to use this tool versus the obvious alternative and gives a concrete workflow instruction.
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?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It explicitly warns that overwrite=True irreversibly overwrites ALL matching objects across multiple asset categories and that confirm_overwrite is required. This is excellent transparency for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a clear first-line purpose, a critical warning in caps, and a concise parameter breakdown. Every sentence adds value; no fluff or repetition. The warning is appropriately prominent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which means return values need not be described), this description covers all essential aspects for a safe and correct use: what the tool does, how to use the parameters, and the irreversible overwrite risk. It is complete for the tool's complexity and destructive potential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It does exactly that with an Args section defining file_path as an absolute path, overwrite behavior, and confirm_overwrite as a mandatory confirmation. This is essential information not present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: importing Superset assets from a ZIP file. It specifies the source format (ZIP created via assets_export) and distinguishes it from sibling tools like dashboard_import or chart_import by covering all asset types. The verb 'Import' and resource 'Superset assets' 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 Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the primary use case (importing assets exported via assets_export) and provides critical guidance about overwrite behavior. It doesn't explicitly mention alternatives for single-type imports, but the context is clear enough for an agent to select this tool when dealing with a ZIP file of multiple asset types.
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?
With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly warns 'CRITICAL: the dashboard will be permanently deleted' and clarifies the deletion scope, which is essential for a destructive operation. This goes beyond the minimal 'delete' phrasing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear one-line purpose, a critical warning, and a short Args list. Every sentence earns its place without fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a delete tool with an output schema, the description sufficiently covers the essential context: the deletion scope, permanence, and the required confirmation parameter. It does not need to explain return values because the output schema handles that, and there are no other complex behavioral aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The Args section describes both dashboard_id and confirm_delete, adding meaning beyond the schema. It labels confirm_delete as 'REQUIRED', which clarifies that the flag must be set true to actually delete—an important behavioral detail the schema alone (with default false and not in required) does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete a dashboard by ID', a specific verb and resource that clearly distinguishes it from sibling tools like get, update, copy, or list. The scope is further clarified by stating charts and datasets are not deleted.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool (to delete a dashboard) and provides a clear exclusion by noting that charts/datasets are not deleted. However, it doesn't explicitly name alternative tools for those cases, falling short of a full when/when-not/alternatives explanation.
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?
With no annotations, the description fully carries the burden and does so excellently. It details internal behavior: 'Automatically populates chartsInScope with all dashboard charts, builds correct scope, defaultDataMask, and cascadeParentIds' and warns about the required ID format: 'NATIVE_FILTER-<uuid> format — this is REQUIRED for Superset 6.0.1 (custom IDs are silently ignored by the frontend).' This goes far beyond a simple 'Add a filter' statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized for a complex tool. It opens with a one-sentence summary, then provides a short but critical behavioral note (ID format), followed by a structured parameter list. Every sentence earns its place — no filler or redundancy. The format is scannable and aids comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 params, no annotations, specialized defaults) and that an output schema exists, the description is remarkably complete. It covers all parameters, explains the crucial ID format requirement, describes auto-population behavior, and clarifies parameter semantics. This is sufficient for an agent to select and invoke the tool reliably without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It does so comprehensively with an Args section covering all 9 parameters, including examples (name: 'Full Name', column: 'full_name'), clarification (filter_type: 'filter_select', 'filter_time', 'filter_range'), and semantic nuance ('enable_empty_filter: Empty filter means filtering by NULL'). The description adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Add a native filter to a dashboard with correct defaults.' It uses a specific verb ('Add') and resource ('native filter to a dashboard'), and mentions 'correct defaults' indicating specialized behavior. This distinguishes it from sibling tools like superset_dashboard_filter_update and superset_dashboard_filter_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (adding a native filter) and explains key behavior (auto-populates chartsInScope, generates required ID format). However, it does not explicitly state when not to use it or directly compare with alternatives, only implicitly via the 'Add' verb and sibling tool names. This is strong context but lacks explicit exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It reveals pagination behavior, the max page size (100), and get_all's effect of ignoring page/page_size. It does not detail return formats or authentication, but the output schema covers return structure, so this is a strong disclosure of behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: the core purpose is stated first, followed by a critical usage note, then parameter definitions. The RISON examples are lengthy but directly useful for constructing filters, and every sentence adds necessary value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a listing endpoint with pagination and filtering; the description covers all operational aspects: pagination, max page size, filter syntax, and get_all behavior. It also provides a workflow hint (call before dashboard_get) that makes it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description fully explains each parameter: page (starting from 0), page_size max 100, q with concrete RISON examples for title/owner/published filters, and get_all's automatic pagination. This fully compensates for the lack of param descriptions in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists Superset dashboards with pagination, using a specific verb and resource. It explicitly distinguishes itself from dashboard_get by instructing users to call this first to discover dashboard IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: 'always call this tool before dashboard_get' and explains pagination parameters, filtering options, and the get_all behavior. This tells the agent when to use it and how to use it effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly describes the listing behavior, return fields, pagination, and get_all behavior, as well as the IMPORTANT note about calling before database_get. It does not explicitly state that the operation is read-only, but 'list' implies it, and no contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a clear purpose, followed by return fields, an important usage note, and a structured Args section. Every sentence contributes value, and the parameter details are necessary given the schema's lack of descriptions. It is well-organized and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's behavior, parameter semantics, and usage context. It explains return values despite having an output schema, provides examples for filters, covers pagination semantics, and includes the crucial sequencing directive with database_get. The output schema covers return details, so the description is complete for this simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides zero description coverage for parameters, so the description must fully compensate. The 'Args' section explains every parameter (page, page_size, q, get_all), includes RISON filter examples, mentions the page size max, and clarifies that get_all ignores page/page_size. This far exceeds the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List database connections configured in Superset.' It also states the return fields (ID, name, engine type, status), and explicitly distinguishes itself from the sibling tool database_get by instructing the agent to call this tool first to discover current IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'IMPORTANT: always call before database_get to discover current IDs.' It also provides parameter-level usage guidance for pagination and get_all, and explains the q filter with examples. This directly addresses when to use this tool vs the listed alternative.
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 behavioral trait: 'Superset PUT API REPLACES the roles and tables fields entirely.' It explains the risk of wiping data if only one field is passed and mandates that both be provided together. No annotations are present, so this warning is essential and excellently highlighted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well structured: a one-line purpose, a prominently placed CRITICAL warning, numbered steps, and a clear Args list. All content is essential and non-redundant. The warning is front-loaded to ensure the agent notices it before making changes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, conditional requirements, destructive replacement behavior) and absence of annotations, the description fully covers the critical context. It explains the prerequisite (retrieve current rule), the conditional parameter requirements, and the meaning of each field. The output schema exists, so return values need not be described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries full responsibility for parameter meanings. It defines every parameter in the Args section, including types (e.g., 'List of dataset IDs'), constraints (e.g., 'REQUIRED if roles is specified'), and allowed values (e.g., filter_type: 'Regular' or 'Base'). This is far beyond what the input schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an RLS rule.' which is a specific verb+resource statement that clearly establishes the tool's purpose. This distinguishes it from sibling tools like superset_rls_create, superset_rls_list, superset_rls_get, and superset_rls_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit safe-update steps: '1. First get the current rule via rls_list 2. Pass BOTH roles AND tables'. This tells the agent when to use the tool and references an alternative tool for a prerequisite. However, it does not explicitly state when not to use the tool (e.g., for creating a new rule), so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It prominently warns that the endpoint REPLACES ALL role permissions, highlights that confirm_full_replace is required, and even explains how to perform a single add safely. This goes well beyond what annotations would provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with a critical WARNING, followed by clear steps and parameter explanations. It is slightly repetitive because the Args section restates some schema information, but each line adds meaningful context, especially the warning and the single-add procedure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a destructive permission-replacement tool with no annotations, the description covers the essential context: the risk, the required confirmation flag, how to obtain permission IDs, and how to achieve a single-add through a get-then-set pattern. Since an output schema exists, the absence of return-value details is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to all three parameters: role_id is clearly labeled as a Role ID, permission_view_menu_ids is described as the full list with a reference to superset_permission_list, and confirm_full_replace is described as a confirmation flag. However, it calls confirm_full_replace 'REQUIRED' while the input schema marks only role_id and permission_view_menu_ids as required, a slight inconsistency with the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Set the permissions list for a role (FULL REPLACEMENT).' This uses a specific verb ('Set'), names the resource ('role permissions'), and emphasizes the destructive full-replacement behavior. It clearly distinguishes this from sibling tools like superset_role_permissions_get, which retrieves the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly warns that the endpoint replaces all role permissions and provides a step-by-step workflow for adding a single permission: get current IDs via superset_role_permissions_get, add the new ID, and pass the full list with confirm_full_replace=True. It also tells users where to obtain permission IDs (superset_permission_list), making usage guidance actionable and superior to simple context.
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?
No annotations provided, so description carries full burden. Discloses critical behavior that roles REPLACES the entire list, not appends, and requires confirm_roles_replace. Also notes email uniqueness and the partial update semantics. These are key behavioral traits beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with an opening imperative, an IMPORTANT callout, and a bulleted Args list. Every sentence provides essential information; no filler. At ~150 words, it is appropriately sized for a 7-parameter mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all critical aspects: partial update, role replacement behavior, confirmation requirement, uniqueness constraint, and a workflow for adding roles. Given the tool's complexity and no annotations, this is complete enough 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.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description's Args section explains each parameter in plain language, including the semantics of roles ('REPLACES all current roles'), confirm_roles_replace ('REQUIRED when passing roles'), and active ('Activate/deactivate the account'). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update a user' and specifies partial update semantics ('Only pass the fields you want to change'). It distinguishes from sibling tools like user_create, user_delete, and user_get by focusing on modification of existing users. The role replacement caveat further clarifies the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions that only fields provided are changed, implying usage for modifying existing users. Provides explicit alternative: 'get the current roles via user_get' when adding a single role. However, it does not explicitly state when not to use or compare to create/delete, so not a full 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?
With no annotations, the description carries full burden. It discloses destructive behaviors: params, query_context, and dashboards all replace entirely. It highlights the critical date format requirement and the mandatory confirm_params_replace flag when passing params. This goes far beyond basic update semantics and prevents common agent mistakes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a structured Args list. Each sentence earns its place, including the nested warnings. While long, the complexity of the tool justifies the length, and the formatting aids scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no annotations, and no schema descriptions, the description fully covers all parameters, provides cross-references to chart_create and chart_get, and explains the tricky replacement/dependency behaviors. The output schema exists, so return values need not be explained. This is complete for a complex mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. Every parameter is described with purpose and critical constraints, including format references, replacement semantics, and required confirmation. It adds meaning well beyond the bare schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an existing chart' which clearly specifies the verb (update) and resource (existing chart). It distinguishes from chart_create by explicitly saying 'existing' and from chart_get by using 'update'. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Pass only the fields to change' implies partial updates. It directs the user to chart_get for current params and chart_create for valid types, giving clear context on how to use the tool correctly. It also warns about the need to update query_context when params change, which is valuable usage advice.
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?
With no annotations provided, the description carries the full burden and does so excellently. It discloses the API returns {} without a tag ID, the workaround of calling superset_tag_list, and the broken direct attachment endpoints. These are significant behavioral quirks beyond what schemas 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an 'IMPORTANT' callout, a clear behavioral note, and an Args section. Every sentence provides essential information without fluff, making it appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and a sparse schema, the description is remarkably complete. It covers creation behavior, attachment process, return quirks, and parameter formats. While it doesn't mention permissions or duplicates, the provided context 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.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names and types with zero descriptions. The description adds rich meaning for each parameter, especially objects_to_tag with its JSON format, element pairs, and allowed object types. This fully compensates for the schema's lack of semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new tag and optionally attach it to Superset objects,' which is a specific verb and resource. It distinguishes from sibling tools like superset_tag_list, superset_tag_update, and superset_tag_delete by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it mentions that object attachment is only possible during creation, warns that direct attachment endpoints do not work in 6.0.1, and instructs to call superset_tag_list to obtain the new tag's ID. This effectively tells when to use this tool and what alternatives to use.
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?
With no annotations, the description carries full behavioral burden and does so well. It discloses the important API quirk that tag creation returns an empty object and requires a subsequent tag_list call, explains the pagination behavior (get_all ignores page/page_size), and mentions max page_size. These are non-obvious behaviors beyond a simple 'list' label.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a brief contextual explanation, a highlighted IMPORTANT note, and a clean Args list. Every sentence adds value—no fluff or redundancy—and the structure makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list with optional filters) and the presence of an output schema, the description is complete. It covers the essential workflow (get IDs before updating), pagination, filtering syntax, and the API quirk about creation, leaving no critical gaps for an agent to invoke it successfully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions (0% coverage), but the description compensates thoroughly: page (starting from 0), page_size (max 100), q (with a concrete RISON filter example), and get_all (automatic pagination, ignores page/page_size). Every parameter is meaningfully explained with usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'List Superset tags' with a specific verb and resource. It clearly identifies the tool's purpose as a list operation for tags, distinguishing it from siblings like tag_get, tag_create, and tag_update by positioning it as the preliminary discovery step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'always call before tag_get/tag_update to find current IDs' and 'When creating a tag, the API returns {} without an ID — use tag_list to get the ID.' This clearly tells the agent when to use this tool versus alternatives, including a specific workflow rule.
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:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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/bintocher/mcp-superset'
If you have feedback or need assistance with the MCP directory API, please join our Discord server