Draxlr

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the prerequisite workflow, which is useful, but says nothing about what happens to the dashboard on failure, whether re-adding the same query duplicates a widget, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action and followed by the prerequisite chain. No filler or redundancy; every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and a mutation with five parameters, the description covers the essential prerequisites so an agent can call it correctly. It stops short of describing post-call behavior or error conditions, but the core guidance is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter including the displayType enum is already documented in the schema. The description restates the origin of queryId and dashboardGroupId, which the schema properties already note, adding only marginal value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('add a query as a widget to a dashboard'), which is unambiguous and clearly distinct from siblings like draxlr_save_query, draxlr_run_query, or draxlr_get_dashboard. An agent can identify the exact operation without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly names the prerequisite tools and the order to call them: draxlr_save_query to obtain a queryId and draxlr_list_dashboards to obtain a dashboardGroupId. This is direct when-to-use guidance tied to sibling tools rather than vague inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds meaningful context by disclosing that it returns a *short-lived* download link, which is not in the annotations and matters for an agent deciding whether to act on the result immediately.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what the tool does, then the prerequisite, then the return behavior. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only export tool with no output schema, the description supplies the essential pieces: what gets exported, the formats, the prerequisite for the required ID, and the nature of the return value (short-lived link). Nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter (theme, format, showFilters, dashboardGroupId) is already documented in the schema. The description only restates the format choice and dashboard-wide scope, adding little beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Export) and resource (an entire dashboard group) with explicit scope note that all widgets are included, and names the two output formats. This clearly distinguishes it from draxlr_export_query, which exports a single query rather than a dashboard.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to draxlr_list_dashboards to obtain the required dashboardGroupId, giving a clear prerequisite. It doesn't spell out when to prefer this over draxlr_export_query, but the resource-level distinction (dashboard vs query) makes the choice fairly obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds genuine value beyond that by noting the return is a short-lived download link and clarifying both query types are supported.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the core action front-loaded, followed by supported scope, prerequisite sourcing, and return format. No filler; each sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by describing the return value (short-lived download link). Combined with format options, queryId provenance, and supported query types, an agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both queryId and format are already documented in the schema, including the enum and default. The description echoes the queryId source and format options but adds little syntax or meaning beyond the schema, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (export a saved query's results) and names the output formats (CSV, Excel/.xlsx). It also scopes which query types are supported (raw SQL and query-builder), letting an agent distinguish it from draxlr_export_dashboard without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent where to source the required queryId (draxlr_list_saved_queries or draxlr_get_query), which is actionable routing. It lacks an explicit when-not or a named alternative for viewing results instead of exporting (e.g., run_saved_query), so it stops short of full 5-level guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds valuable non-schema context by saying what comes back (widget name, display type, query) plus a viewable `url` — useful precisely because there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the action and lookup key come first, the example use case second, and the return summary last. No filler and nothing buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description helpfully summarizes the return payload and the url, and annotations handle the safety semantics. It could still mention failure behavior for a nonexistent dashboard id or whether widget queries are fully expanded.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both ids are already documented as the :databaseId and :dashboardGroupId link segments. The description only restates this framing, adding no extra syntax, format, or constraint detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a dashboard's widgets by its id'), which is clearly a single-dashboard fetch rather than a list. It does not explicitly name a sibling to contrast with (e.g., draxlr_list_dashboards vs. draxlr_export_dashboard), so differentiation is only implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete use case — resolving a dashboard link of the form /dashboard/:databaseId/:dashboardGroupId — which tells the agent exactly when this tool fits. It stops short of stating exclusions or naming alternatives for the list/export variants.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds materially useful context beyond that: results are permission-filtered ('Only tables the user can access are returned'), which tells the agent the output may be incomplete relative to the actual database.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the purpose, then the query-writing caveat, then the permission caveat. Nothing is redundant and each sentence carries a distinct fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema, the description compensates reasonably by describing the return shape (tables, columns, data types) and the access-scoping behavior. Only minor gaps remain, such as whether results are paginated for very large schemas.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single parameter points back to draxlr_list_databases, so the schema does the heavy lifting. The description adds no format or syntax detail about databaseId itself; the `name` guidance concerns the response, not the input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get a database's schema') and immediately specifies the payload: tables, columns, and data types. This is clearly distinct from draxlr_list_databases, which only yields IDs, so an agent can route between them without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The clause 'so you can write correct SQL' establishes the intended moment of use, and the note to reference table/column `name` rather than display names is actionable invocation guidance. There is no explicit when-not or named alternative, but the workflow context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds useful behavioral context by listing the returned fields (name, description, type, SQL, url) and explaining the 'type' values ('raw' SQL or 'builder'), which helps the agent anticipate the 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by return details and link format. Every sentence earns its place without redundancy, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read tool with full schema coverage and rich annotations, the description covers what the tool does, how to obtain the required id from a link, and what the response contains. No output schema exists, and the description compensates by describing return fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by giving the full link pattern /explore/:databaseId/:tableId/:queryId and noting that :tableId is 'raw_query' for raw SQL queries, which contextualizes why databaseId is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Get') and resource ('details of a saved query by its id'), and clarifies the return fields. It does not explicitly name a sibling to differentiate from (e.g., list_saved_queries), but the 'by its id' scoping makes the individual-vs-list distinction reasonably clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a use case example ('for example to resolve a query link'), which implies when to use it, but offers no explicit when-not guidance or alternatives. The intended usage is inferable but not spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds value beyond that by disclosing the return shape (id, name, database) and the non-obvious id reuse hint ('use as dashboardGroupId'), which an agent cannot infer from 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with scope, then filter, then return values. No filler or redundancy; every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-param read tool with a fully documented schema, the description covers scope, filter, and return fields. It omits any pagination or result-limit behavior, which is the only gap for a list operation with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the single parameter is fully documented as an optional database filter; the description repeats that behavior without adding syntax or format detail. Baseline 3 applies when the schema carries the parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List dashboards in the Draxlr organization') and clarifies scope (org-wide, optional database filter). It does not explicitly distinguish itself from siblings like draxlr_list_databases or draxlr_get_dashboard, though the resource noun is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Optionally filter by databaseId' implies when to apply the filter, but there is no guidance on when to pick this tool over draxlr_get_dashboard (single dashboard) or draxlr_list_databases (parent resource). Usage 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful fact that no filtering/parameters apply and enumerates the returned fields (id, name, type, active status), which matters since there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the purpose and followed by the return shape and the workflow tip. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only listing tool with no output schema, the description supplies everything an agent needs: what it lists, what fields come back, and how to reuse the id. Annotations cover the safety profile, so nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, and the schema itself is empty with full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource with scope: 'List all databases connected to the Draxlr organization.' The resource (databases) is clearly distinguishable from siblings like draxlr_list_dashboards and draxlr_list_saved_queries without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable downstream guidance — 'Use the id as `databaseId` for the other tools' — which tells the agent why and when to call this. It stops short of explicit when-not or alternative-tool routing, so it falls just below the top tier.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description earns credit by disclosing the return shape that no output schema provides, including the `type` enum values ('raw' vs 'builder') and the builder-only `tableId` field.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, zero waste, front-loaded with the core action and then the return contract and the downstream chaining. Every clause carries usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and only one trivially documented parameter, the description fills exactly the gap that matters by describing the returned fields and their semantics. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter has 100% schema coverage, so the schema already documents `databaseId` and its provenance from draxlr_list_databases. The description adds no further detail about the input parameter itself, only about the id it returns, so this lands at the high-coverage baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List the saved queries for a Draxlr database') and immediately enumerates what each item contains (id, name, description, SQL, type, tableId). An agent can distinguish this from draxlr_list_databases and draxlr_get_query without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent forward by saying the returned id is used as `queryId` for draxlr_add_query_to_dashboard, draxlr_run_saved_query, and draxlr_export_query. It does not state when NOT to use this tool (e.g. to fetch a single query, use draxlr_get_query), so it falls short of full when/when-not coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is to add beyond them. It does: it discloses that only SELECT is permitted and describes what the call returns (a queryId and a url), which is behavior the annotations do not convey. It omits failure modes and row-limit behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, each earning its place: purpose, the read-only restriction, and the return contract with downstream consumers. Front-loaded with the core action and no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by explaining the returned queryId and url and their downstream use. Combined with a 100%-covered input schema and safety annotations, the definition is largely self-sufficient; only pagination-limit/error behavior is unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the sql parameter's schema description is very rich (variable syntax, [[ ]] conditional wrapping, variable typing), so the schema carries the parameter burden. The description adds no parameter-level detail beyond a general reference to variables, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a read-only SQL query against a Draxlr database and return the resulting rows') and scopes it precisely to SELECT-only. It also names the downstream tools that consume its output (draxlr_save_query, draxlr_add_query_to_dashboard), which helps separate it from sibling read tools like draxlr_run_saved_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The constraint 'Only read (SELECT) queries are allowed' effectively signals when the tool is not appropriate, and the return payload tells the agent this is the entry point for ad-hoc SQL. It never explicitly names an alternative (e.g. draxlr_run_saved_query for saved queries), so routing between the two is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds genuine context beyond them: it works for both raw SQL and query-builder saved queries, and that it returns resulting rows. It does not discuss pagination behavior or whether results are truncated, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action, then the prerequisite, then the alternative. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only query runner with no output schema, the description covers the action, the source of the required id, the acceptable query types, and the return shape (rows). Pagination semantics are left entirely to the schema, but nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so queryId, page, pageSize and databaseId are already documented in the schema, including the fallback resolution of databaseId. The description adds no syntax or format detail beyond restating where queryId comes from, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: run an existing saved query by id and return resulting rows. It explicitly distinguishes itself from draxlr_run_query (ad-hoc SQL), so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit prerequisites (obtain a queryId via draxlr_list_saved_queries or draxlr_get_query) and names the alternative tool for a different intent (draxlr_run_query for ad-hoc SQL). That is when-to-use plus a named alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states that the provided SQL 'is executed then saved', meaning the tool can run arbitrary SQL that may modify or destroy data. Annotations declare destructiveHint: false, which conflicts with this disclosure and would mislead an agent about the tool's safety profile. This is an annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the main action and scope, and contains no filler. Every sentence earns its place by stating what is saved and the two input modes.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with full schema coverage and annotations, the description is nearly complete: it covers the save operation, destination, and input alternatives. It omits return behavior and permission expectations, but those gaps are minor for a save operation and no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters, including variable syntax and allowed types. The description only restates the sql/queryId either-or choice already present in the schema and adds no meaning beyond it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: saving a SQL query to a Draxlr database so it appears under saved queries. It also distinguishes itself from draxlr_run_query by explaining that sql is executed then saved or that queryId comes from that sibling, allowing an agent to route correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives usage detail for the two input alternatives (sql or queryId from draxlr_run_query), but it does not explicitly state when to use this tool versus draxlr_update_saved_query, draxlr_run_saved_query, or draxlr_add_query_to_dashboard. Usage is implied by the purpose rather than fully guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish that this is a read-only, idempotent, closed-world operation, so the safety profile is covered. The description adds genuinely useful behavior beyond that: what is returned (matching queries/dashboards with ids and view links) and how the id is meant to be consumed downstream.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the action and scope, followed by return contents and the follow-up routing. No filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by describing the return shape (ids and view links) and the next-step tools. For a two-parameter read-only search tool with full schema coverage and annotations, nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (query, databaseId) are already fully documented, including the pointer to draxlr_list_databases for obtaining the id. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and a specific resource scope (saved queries and dashboards by name), which cleanly separates it from draxlr_list_saved_queries and draxlr_list_dashboards, which enumerate rather than search. An agent can distinguish it from all siblings without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells the agent what to do with results, explicitly naming draxlr_get_query, draxlr_run_saved_query and draxlr_get_dashboard as consumers of the returned id. It implies the usage condition (find by name) but does not state when to prefer this over the sibling list tools for discovery.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing what is returned (title, snippet, link), which matters because no output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first describes what is searched and returned, the second states when to use it. Front-loaded and free of filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter read-only search with no output schema, the description covers scope, return contents, and invocation context. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: both 'query' and the 'limit' bounds/default are documented in the schema itself. The description adds no syntax, scoping, or matching-behavior detail beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (search) and resource (Draxlr's product documentation), enumerates covered topic areas, and describes the return shape (title, snippet, link). An agent can immediately tell this apart from data-query siblings like draxlr_run_query or draxlr_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit usage context: 'Use this to answer how do I… questions about using Draxlr.' That is clear routing guidance, but it does not name or exclude the ambiguous sibling draxlr_search, so the agent must infer which search surface applies.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the mutation/replacement risk profile is largely covered. The description adds the useful constraint that only raw SQL queries can be updated, but it does not expand on the destructiveness of replacing SQL or on failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler: the update action and its scope come first, with the prerequisite inputs and their source immediately after. Nothing can be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter mutating tool with a nested variables object, no output schema, and annotations covering the safety profile, the description supplies the essential inputs, their source, and the raw-SQL restriction. Minor gaps remain around whether variables can be updated without replacing sql and what the response confirms.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema already explains each parameter, including the detailed {{variable}} syntax and the roles of name/description/queryId. The description restates the field list and the queryId source but adds no syntax or format meaning beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Update an existing saved query') and enumerates exactly which fields change (rename, description, SQL), plus a scope constraint ('raw SQL queries only'). It is clearly distinct from the read/list siblings, though it never explicitly contrasts with draxlr_save_query, so it falls short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It tells the agent how to invoke it correctly: supply queryId sourced from draxlr_list_saved_queries and at least one of name/description/sql, which conveys the partial-update model. There is no explicit when-not-to-use guidance or named alternative (e.g., save_query for creating new ones).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.