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

Annotations only supply destructiveHint=false and a title, so the description carries the real burden — and it does: it discloses the auth prerequisite, the non-obvious side effect that the new account becomes the active account (changing what projects_create/projects_list target), and the return payload. Creation is not idempotent-safe by implication, and the 'check first' warning covers the duplicate-account risk.

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?

Four tight sentences, front-loaded with the action, followed by prerequisite, side effect, return value, and the routing hint. Every sentence carries information an agent needs and there is no filler or restatement 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?

There is no output schema, and the description compensates by stating what is returned (the new account's id and name). Combined with the login prerequisite and the active-account side effect, an agent has everything needed to call this correctly and sequence it properly.

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 name, email, and currency (including the immutable-after-creation constraint and default) are already fully documented. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a new billing account (organization)') plus what the resource holds ('projects and payment details'). It is immediately distinguishable from siblings like accounts_list, accounts_use, and projects_create, which are all named explicitly.

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 preconditions ('Requires a prior platform login (use the login tool first)') and an explicit when-not/gate ('Most users need only one account — call accounts_list first to check whether a suitable one already exists'). Nothing about tool selection 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 readOnlyHint=true, so safety is covered, yet the description adds real value: an authentication prerequisite, the exact fields returned (id, organization name, billing email, currency, status), the Active/Suspended/Canceled enumeration, and which account is currently active. It stops short of stating side effects or pagination, but there are none expected for a zero-arg 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.

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

Three sentences, front-loaded with what is listed, then the auth prerequisite, then the downstream action. Every sentence carries distinct information with no restatement of the name or 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?

There is no output schema, and the description compensates by enumerating the returned fields and status values plus the 'currently active' flag. Combined with the auth prerequisite and sibling routing, nothing needed to call this tool 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 tool takes no parameters, so the baseline of 4 applies; the description correctly implies no filtering or input is required. There is no filter syntax or scoping option to explain.

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 (List) and resource (billing accounts/organizations), and disambiguates by clarifying parenthetically that accounts are organizations. It also situates itself among siblings by naming accounts_use as the follow-up action, so an agent can separate it from accounts_create without opening schemas.

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?

Explicit prerequisites ('Requires a prior platform login (use the login tool first)') and explicit next-step routing ('pick one with accounts_use before creating or listing projects'). Both when-to-use and the relevant alternative are stated, not implied.

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?

With only destructiveHint=false in annotations, the description carries most of the load and does well: it discloses the accepted input forms, that it resolves to a name/id on success, and that a non-matching id yields an error. It stops short of stating auth requirements or whether the switch persists across sessions, so not a full 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 tight sentences, front-loaded with the effect, followed by the sequencing guidance and the return behavior. No filler; every 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?

For a single-parameter switch tool with no output schema, the description covers effect, prerequisites, input forms, and success/failure outcomes. Nothing an agent needs to invoke 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 coverage is 100% and the single id parameter is fully documented in the schema, including the full-UUID-or-unique-prefix semantics and the accounts_list pointer. The description's mention of the same details adds little beyond what the schema already states, so 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 (Set) and resource (active billing account that project commands operate on), and positions itself clearly against siblings accounts_list and accounts_create. An agent can distinguish this from projects_use and config_use 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 names the precondition ('after login'), the condition ('when you belong to more than one account'), and the downstream tools that depend on it ('projects_list', 'projects_create', 'projects_use'). It also routes to accounts_list for id discovery, leaving little 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds meaningful context beyond them: the exact categories of routes returned and the return format ('Returns JSON'), which matters since no output schema exists. It does not mention auth needs, pagination, or ordering, but the annotated baseline keeps the bar reasonable.

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?

Purpose is front-loaded in the first sentence, followed by scope detail, usage, and return format. The middle enumeration is dense but each clause carries distinct scope information, so little is wasted.

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-only listing tool with a fully documented parameter and no output schema, the description covers what is listed, why to use it, the alternative for invocation, and the return format. Missing only minor operational details such as auth or pagination behavior.

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?

One parameter (`base_url`) with 100% schema description coverage, so the schema already documents it. The description adds no parameter-level information, which matches the baseline of 3 for high schema 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 ('List all API endpoints') and elaborates its scope: platform core routes plus dynamically generated entity CRUD/public routes and workflow-triggered routes. It also distinguishes itself from the sibling `fetch`, so an agent can tell what this does versus calling an endpoint.

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 clear condition ('Use it to give app developers endpoint URLs') and names the alternative for a related need ('to call one, use `fetch`'). There is no explicit negative scope (e.g., when not to use it versus `docs`), so it stops short of the full when/when-not/alternatives bar.

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?

Rich disclosure beyond the annotations: the raw key is shown once and never retrievable, expiry is 1–365 days (90 default), permissions the caller lacks are silently dropped with a warning, and the key lands only in the output or a CLI profile. These are the exact behavioral facts an agent needs and none are in the annotations.

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

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

Front-loaded with the core action and generally tight. The 'shown once and never retrievable' / 'appears only in this output... store it at once' pairing is mildly redundant, and the trailing 'Returns JSON' adds little, but the paragraph earns its space overall.

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 carries return information and does so adequately, emphasizing that the raw key is delivered once in the output. Annotations cover the safety profile (non-readOnly, non-destructive). Minor gap: it doesn't describe the JSON shape returned, but the critical one-time-secret caveat is covered.

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% (baseline 3), and the description adds meaning on top: save_as diverts the raw key into a CLI profile, expires_in semantics/range, and that requested permissions fall back to what the caller actually holds. Slightly exceeds what the schema alone conveys.

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 (Create) and resource (API key / project API key) with concrete scope details: permissions, expiry, and where the raw key goes. An agent can distinguish this from api_keys_list and api_keys_revoke 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?

Usage is largely implied by the create verb rather than stated. It hints at the save_as alternative ('goes straight into a CLI profile with save_as') and points to `fetch` on /permissions for valid names, but gives no explicit when-to-use/when-not guidance or comparison to sibling tools.

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=true and openWorldHint=false, so the safety profile is given. The description adds genuinely useful context beyond that: which fields are exposed, the status classification (active/expired/revoked), and the security-relevant guarantee that key values are never returned. Missing pagination/size behavior keeps it from 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?

Two tight sentences: purpose first, then the returned fields and the security note, then the cross-reference. Every clause 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?

With no parameters and no output schema, the description compensates by enumerating the returned fields and statuses, so an agent knows exactly what to expect from a call. Nothing needed 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing further the description could clarify about inputs.

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 API keys for the current user'), clearly distinguishing it from siblings like api_keys_create and api_keys_revoke. An agent can identify it 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?

Explicitly routes the agent downstream: 'Use the id with `api_keys_revoke`', which names the consuming tool. It does not state when-not to use it or list other alternatives, 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.

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

Goes well beyond the destructiveHint annotation by spelling out irreversibility (immediately and for good), the concrete downstream consequence (scripts, CI jobs, CLI profiles failing to authenticate), and a user-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.

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

Three tight sentences, front-loaded with the action and consequence, followed by the prerequisite and safety caution. 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?

For a one-param destructive mutation with a complete schema and annotations, the description covers safety, irreversibility, prerequisites, and consequences. No output schema needed and nothing an agent requires 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% and the single param is fully documented there, including how to find the ID via api_keys_list. The description only restates 'by ID,' adding no meaning 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 (revoke) and resource (API key) with the identifying argument (by ID), and the `api_keys_revoke` name plus description clearly separate it from api_keys_create/list siblings.

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 advises creating a replacement with `api_keys_create` first if access is still needed and to check with the user before running. It provides strong preconditions and caution, though it does not enumerate when not to revoke (e.g., shared keys) beyond the general warning.

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 the mutation/read and safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds valuable behavior beyond that: settings are validated and the call is refused with problems listed, and the chart stays invisible until attached to a dashboard. It doesn't detail permission requirements or rate limits.

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

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

Front-loaded with the core action and then packs workflow, side-effect and return-format facts into a few tight sentences with no filler. Every 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?

For a 25-parameter mutation tool with no output schema, the description covers the essential workflow, validation/refusal behavior, and the post-create visibility constraint. It notes 'Returns JSON' but the absence of an output schema leaves return shape largely unstated, a minor gap given the richness elsewhere.

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 parameter docs are very detailed, so the schema carries the semantic load. The description adds no per-parameter meaning beyond what the schema already states, 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+resource ('Create a chart') and immediately clarifies the three data sources it can plot (entity records, platform usage metric, plan quota), naming the relevant sibling charts_platform_metrics. An agent can distinguish it from charts_update/charts_preview 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?

Gives explicit workflow guidance ('Check it first with charts preview') and names where the result must go next (dashboards_add_chart or dashboards_create). It stops short of stating when NOT to use it (e.g. editing an existing chart via charts_update), so it is strong but not fully exhaustive.

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 destructiveHint=true, but the description adds concrete consequence detail beyond that: dangling empty widgets remain on dashboards, deletion is permanent, and it warns to check with the user first. It does not discuss auth requirements or reversibility beyond 'permanently,' which slightly caps the score.

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?

Four sentences, mostly informative, but the follow-up instruction ('find the widgets...clear them') is operational guidance rather than purpose-defining and somewhat pads the length. Front-loaded well with the core action first.

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?

No output schema, so the description notes it returns JSON, though not the shape. Covers the mutation, the side effect on dashboards, and the safety warning. Sufficient for an agent to call it correctly given annotations already flag destructiveness.

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%, giving a baseline of 3; the description adds the operational constraint that the chart ID is required but the schema already says that too. The description's 'find it with charts_list' is already in the schema's parameter description, so no extra value there, but the schema itself is complete.

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 ('Delete') and resource ('chart'), plus the permanent nature of the removal. Explicitly distinguishes itself from the more surgical dashboards_remove_widget by contrast.

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 when-to-use and when-not-to-use: 'To take a chart off one dashboard but keep it, use dashboards_remove_widget instead.' Also prescribes a follow-up workflow (find dangling widgets via dashboards_get, clear with dashboards_remove_widget).

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=true and openWorldHint=false, covering the safety profile. The description adds useful observability context by enumerating exactly which configuration fields are returned and noting the payload is JSON, which goes beyond the annotations.

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

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

Three sentences, front-loaded with the core action, then the returned fields, then routing guidance. No filler; every clause carries 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 single-param read tool with annotations covering safety and no output schema, the description compensates by listing the return contents and stating the format. Nothing an agent needs to call and interpret it 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 coverage is 100% and the single `id` param is documented in the schema with a pointer to `charts_list`. The description adds no syntax, format, or constraint detail beyond what the schema already provides, 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 ('Get a chart's full configuration') and enumerates the concrete settings returned (type, data source, entity/metric, grouping, measure/aggregation, filters, time window, target, comparison). It distinguishes itself from `charts_update` and `dashboards_widget_preview`, so an agent can route correctly without opening schemas.

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 says when to use it ('Read it before `charts_update`') and names the alternative for a different need ('to see the data it draws, use `dashboards_widget_preview` with type chart and its id'). Both the when and the alternative are stated outright.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the newest-first sort order, the returned fields, and JSON output format.

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?

Front-loaded with purpose, then ordering, return shape, filter usage, and domain context. Well ordered; the trailing 'Returns JSON' is minor filler but not harmful.

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 single-parameter read-only list tool with no output schema, the description covers ordering, fields, filtering, and the chart/dashboard relationship. Nothing essential 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 coverage is 100%, so the single `entity` parameter is already documented as 'Only charts that plot this entity'. The description's 'pass entity to see only one entity's charts' largely restates the schema, so 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 ('List charts') plus the ordering ('newest first') and enumerates the exact fields returned (id, name, type, data source, entity/metric, last changed). This clearly distinguishes it from siblings like charts_get, charts_create, and charts_delete.

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?

Explains that passing `entity` narrows results to one entity, and clarifies the chart/dashboard relationship ('appears on a dashboard only once added with dashboards_add_chart'). It stops short of explicitly contrasting this tool with charts_get, but the intended use 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds useful context beyond them: it discloses the shape of each returned record and that the response is JSON. With no output schema present, describing return contents is genuinely valuable, though pagination/error behavior is not mentioned.

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, front-loaded with the core purpose and then the follow-up wiring. Slightly repetitive in restating 'usage metrics a platform chart can plot', but there is no filler and no buried 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 zero-parameter, side-effect-free lookup with no output schema, the description covers what the agent needs: what is listed, what each entry contains, and how to consume the ids downstream. Annotations already carry the read-only safety story, so the remaining gap is minor.

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 still adds meaning by explaining how the returned ids map onto parameters of other tools (platform_metric for charts_preview/charts_create, stack_by for breakdowns), which helps the agent use the output correctly.

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 (List) and resource (usage metrics a platform chart can plot), and enumerates exactly what each entry contains: id, label, shape, supported chart types and breakdowns. An agent can distinguish this discovery/lookup tool from siblings like charts_list, charts_get, charts_preview and charts_create 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?

The description names the concrete alternatives and the workflow: 'Pass a metric's id as platform_metric to charts_preview or charts_create, and one of its breakdowns as stack_by.' That is strong context for when this tool is the right entry point. It stops short of an explicit when-not-to-use or ordering statement, so 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.

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false). The description adds real value beyond them: it clarifies that nothing is saved, that it runs against the project's current data, that output is trimmed to rows, and that it returns JSON. It does not mention auth/permission needs or rate limits, 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 tight sentences, front-loaded with the core purpose, then usage, then return format. No filler; every 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?

For a 25-param, no-required preview tool with no output schema, the description covers purpose, when to use, and a rough return shape ('points, totals or rows', 'Returns JSON'). It is complete enough to call correctly, though it could say more about the returned structure since 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 coverage is 100% across all 25 parameters, so the schema already docs each option in detail. The description reinforces key concepts (entity, grouping, measure, filters, row trimming) but adds no syntax or format detail beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource: preview the data a chart configuration would draw without saving. It explicitly names what it produces (points, totals, rows) and distinguishes itself from `charts_create`, `charts_update`, and `dashboards_widget_preview`, so an agent can select it 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?

Explicit when-to-use: settle entity, grouping, measure and filters before create/update. Also names the alternative for the already-saved case (`dashboards_widget_preview`). Both the positive condition and the routing alternative are 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?

Adds behavioral detail well beyond the annotations: partial-update semantics (unpassed settings persist), the destructive-replace behavior of `filter`, and the non-obvious propagation that dashboard widgets reference the chart rather than copy it, so every dashboard redraws. It also reinforces the user-confirmation requirement consistent with destructiveHint=true.

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?

Front-loads the purpose and keeps each sentence short and on-task, with the safety caution last where it belongs. Mild redundancy between 'Only the settings you pass change' and 'Saves new settings on an existing chart', plus a low-value 'Returns JSON.' line, keep it from a 5.

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 26-parameter mutation with no output schema, the description covers the essentials: partial-update behavior, filter replacement, propagation side effects, prerequisite read, and confirmation. The only weak spot is the vague 'Returns JSON.' in place of any return-shape hint, though the absence of an output schema makes this a minor gap.

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% across all 26 parameters, so the schema already carries the parameter documentation and the baseline is 3. The description adds only the filter-replacement rule, which is also stated in the schema, so there is no meaningful extra parameter insight.

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 ('Change a chart') and immediately qualifies it as a partial update against an existing chart, which separates it from charts_create. It also names charts_get as the read-side sibling to consult first, so an agent can route correctly without opening other schemas.

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 concrete pre-call guidance ('Use charts_get first to see its current settings') and a confirmation rule ('check with the user before running it'). It doesn't explicitly state when NOT to use it (e.g., to create a chart, use charts_create), but the 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 only flag openWorldHint and destructiveHint; the description goes far beyond that by naming the destructive command families (delete, expire, relink, pause), forbidding '--yes' on the user's behalf, mandating human execution of destructive pay commands, and prescribing dry-run-first workflows for import commands. No contradiction with the destructiveHint annotation—it explains it.

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?

Front-loads purpose and the fallback routing before the command syntax and safety rules. Dense but every sentence carries a distinct constraint for a broad escape-hatch tool; minor redundancy with the schema's example list.

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 an open-ended catch-all tool with no output schema, this covers what an agent must know: what it is, when to prefer siblings, exact argument format, and the safety/dry-run obligations for destructive and project-mutating subcommands.

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 schema already documents the single command parameter, including the 'do not include anythink or --profile' rule. The description largely restates that with different examples, adding only the --json hint, 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+resource ('Run any Anythink CLI command and return its output') and immediately positions itself against the many dedicated siblings by declaring itself the fallback ('Prefer the dedicated tools; use this for anything they don't cover'). Concrete examples ('entities list', 'data list posts') make 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.

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

Explicitly says when to use it (anything the dedicated tools don't cover) and when not to (prefer dedicated tools). Adds further conditional guidance: which destructive commands a human must run, and the --dry-run-then-approve protocol for 'data import' and 'import directus'.

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 only supply destructiveHint=true, but the description adds the crucial semantic that destruction is scoped to local credentials/settings and that no server-side revocation occurs — a distinction an agent could easily get wrong. It also discloses the outcome shape ('confirmation, or a not-found message').

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, each doing distinct work: scope of deletion, boundary/exclusion with alternative, and return behavior plus name discovery. The core action is front-loaded with 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?

No output schema exists, yet the description covers the return contract ('confirmation, or a not-found message'), the local-vs-server scope, and how to find valid inputs. Nothing an agent needs to invoke this safely 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% for the single 'profile' parameter, so the schema already documents name and source of valid values. The description's 'Run config_show to see profile names' reinforces this but adds nothing the schema doesn't already state; 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+resource+scope: 'Delete a saved project profile from the local CLI configuration.' The qualifier 'from the local CLI configuration' immediately distinguishes it from the similarly named sibling 'projects_delete', which the description also explicitly names.

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 an explicit when-not clause ('it does not delete the project or revoke tokens server-side') with the correct alternative named ('to remove the project itself, use projects_delete'). It also routes the agent to 'config_show' to discover valid profile names, covering the pre-call lookup step.

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 annotations declare readOnlyHint=true, but the description adds the important behavioral fact that it 'Reads local config only — makes no network calls,' which is beyond what annotations provide. It doesn't cover error states or edge cases (e.g., no config file), keeping it from 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?

The description is front-loaded with the main purpose and then details the return payload; it is two dense sentences with no fluff, though the second sentence is long.

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 zero parameters, the description fully specifies what is returned (profile fields and platform details) and its side-effect-free local nature, leaving no gaps for an agent to call 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, and the schema coverage is 100%.

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 ('Show the local CLI configuration: all saved project profiles and platform logins') and drills into exact returned fields, making its purpose unmistakable against siblings like config_use or config_remove.

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 alternatives it feeds into ('discover profile names for config_use, config_remove, or logout') and its diagnostic use case ('check which project the cli tool currently targets'), providing clear when-to-use context.

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 only declare destructiveHint=false, so the description carries most of the burden and does well: it discloses the state-mutating effect (which profile the cli operates against), the prerequisite that the profile pre-exist, and the error condition when it doesn't. It stops short of describing persistence or side effects on in-flight sessions, so not a full 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 sentences, front-loaded with the action, then usage rationale, then prerequisites and return behavior. Every sentence earns its place with 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 single-parameter, non-destructive mutation with no output schema, the description covers prerequisites, alternatives, and return behavior ('confirmation, or an error'). Complete enough for correct invocation; only marginal behavioral detail is absent.

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 schema already documents the 'profile' parameter including the 'See config_show for valid names' pointer. The description restates the existence constraint without adding format or syntax detail, so 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+resource ('Switch the active project profile') and goes further by naming the exact consumer ('the cli tool's commands operate against'). This distinguishes it from sibling config tools like config_show and config_remove without the agent needing to open 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?

Explicitly states when to use it ('move between already-connected projects without re-authenticating'), states the prerequisite ('profile must already exist'), names the creating alternatives ('projects_use' or 'login_direct'), and routes to config_show for valid names. Both usage context and alternatives are fully covered.

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 and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond them: non-destructive semantics ('Everything else on the dashboard stays as it was') and default behaviors for title and widget placement. Only the return value is thin ('Returns JSON'), which limits it from 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?

Four tight sentences, front-loaded with the core action, then defaults, then the routing guidance. No filler; each sentence adds a distinct, useful 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 non-destructive additive mutation with full annotations and no output schema, the definition covers action, non-destructiveness, defaults, prerequisites, and the sibling to avoid. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds interpretation beyond the per-parameter schema: it explains that title defaults to the chart's name and that position/placement is governed collectively by column, row, width and height on a 12-column grid, and defaults to after existing widgets when none are given. This exceeds what each isolated schema entry conveys.

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 ('Add a chart to a dashboard as a new widget') and immediately distinguishes itself from siblings by naming `charts_create` (prerequisite) and `dashboards_update` (the wrong tool, since it replaces every widget). An agent can tell it apart from other dashboard tools without opening schemas.

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?

Explicit when-to-use ('This is how a saved chart gets onto a dashboard'), an ordering prerequisite ('Create the chart first with `charts_create`'), and an explicit when-not-to-use with reason ('avoid `dashboards_update` for this, as it replaces every widget'). Nothing 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?

Beyond the annotations' safety profile, it discloses the ownership model ('owned by you'), the visibility semantics ('visible only to you unless shared is set'), the auth gate on default ('administrators only'), the chart-id-to-widget mapping behavior, and that it returns JSON. This is substantive context annotations alone would not convey.

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

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

Six short clauses, front-loaded with the core action, then ownership/visibility, then routing, then the admin caveat. Every sentence carries distinct information with no 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?

With 8 params, full schema coverage and safety annotations, the description covers the meaningful gaps: prerequisites, ownership, sharing, and admin gating. The return value is only 'Returns JSON' with no output schema, a minor gap, but not one that would cause an incorrect call.

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%, so the baseline is 3. The description adds real meaning beyond the schema: it explains that each chart id becomes a widget titled with the chart's name, and clarifies the shared/default interplay. It stops short of detailing the config JSON structure, which the schema already summarizes.

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 ('Create a dashboard') and immediately adds scope ('optionally with charts already on it'), which distinguishes it from dashboards_update and dashboards_add_chart. An agent can tell what this does 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?

Routes explicitly to alternatives with conditions: 'add more later with dashboards_add_chart' and 'Build the charts first with charts_create'. It also flags the prerequisite for the default flag ('needs an administrator'), leaving little 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context: it runs widgets, returns each widget's id/title/type/current data, and trims output to rows per widget. It could still note cost/latency of running all widgets, but this is solid added value.

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 front-loaded sentences with zero filler, moving from purpose to mechanism to routing to return format. Every 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?

Complete for a read-only tool: all parameters are schema-documented, the alternative is named, and the return shape is described even though no output schema exists. Nothing needed 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 all three parameters (id, rows, widget) are already documented in the schema. The description restates widget filtering and row trimming but adds no syntax or defaults beyond what the schema provides, so 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: gets the data behind a dashboard's widgets by running them and showing id, title, type and data. It clearly distinguishes itself from dashboards_widget_preview by scope (saved dashboard vs. unattached widget).

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 says when to use it ('read what a dashboard shows now') and names the alternative ('use dashboards_widget_preview to try a widget that isn't on a dashboard yet'). The selection condition is fully specified.

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 declare destructiveHint=true, and the description adds real behavioral context beyond that: widgets are destroyed but charts are preserved, the removal affects everyone who can see it, and a deleted home dashboard falls back to the project default. This is exactly the impact detail an agent needs before a destructive call.

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?

Impact and routing information is front-loaded in tight sentences, with the destructive warning last where it belongs. 'Returns JSON' is low-value filler that keeps it from a 5.

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 destructive tool with no output schema, the description covers blast radius, sibling routing, and the home-dashboard edge case. The only thin spot is the vague 'Returns JSON' in place of any return-value detail, which is minor given 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?

There is a single id parameter and schema coverage is 100%, with the schema itself pointing to dashboards_list for discovery. The description adds no syntax or format detail for id, so the baseline 3 for a fully documented schema 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 and resource ('Delete a dashboard') and immediately clarifies scope with 'and its widgets. The charts on it are kept.' An agent can distinguish this from charts_delete and dashboards_remove_widget 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?

Explicitly names the alternatives and the conditions that select them: use dashboards_remove_widget to take one chart off, charts_delete to delete a chart itself. It also states the correct precondition ('check with the user before running it') for a destructive operation.

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=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that — it enumerates the returned fields (name, description, sharing settings, owner, per-widget id/type/title/chart/grid position) and states the format is JSON, which matters given 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?

Front-loaded with the core action, then return contents, then usage routing. Dense but every clause carries information; the field enumeration is slightly long but justified by the absence of an output schema.

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 tool with no output schema, the description compensates by describing the return payload in detail and routing to consuming siblings. Nothing an agent needs to call and interpret 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% and the single `id` param already documents itself ('Find it with dashboards_list'). The description adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

Specific verb+resource (get a dashboard) with scope explicit — 'with its widgets and their positions' — which distinguishes it from dashboards_list and dashboards_mine without opening either schema. An agent can tell exactly what it retrieves.

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 names two downstream siblings that consume widget ids (`dashboards_remove_widget`, `dashboards_data`) and the pre-update read pattern for `dashboards_update`. This is textbook when-to-use guidance tied to concrete alternatives.

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=true and openWorldHint=false, so safety is covered. The description adds useful context beyond that: the exact attribute set returned, the home/default/shared classification, and that the payload is JSON. It does not mention pagination or result-size behavior, which is the only notable gap for a 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.

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

Three sentences, front-loaded with the action and return fields, with the routing guidance last. The middle sentence defining a dashboard as 'a grid of widgets' is mildly tangential but earns its place by making the relationship to dashboards_get concrete; overall tightly written with 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?

For a zero-parameter, read-only list tool with no output schema, the description covers the essentials: what is listed, what fields come back, and which sibling to use next. Minor omissions such as pagination or ordering prevent a 5, but an agent has everything needed to call 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is no parameter syntax or format for the description to clarify, and the text correctly does not invent any.

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 dashboards you can see') and immediately enumerates the returned attributes (id, name, owner, home/default/shared). It also names the sibling tools it is not (dashboards_get, dashboards_mine), so an agent can distinguish it 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?

Explicitly routes the agent: use dashboards_get to inspect a dashboard's widgets and dashboards_mine for the one you land on. The when-to-use-this vs. alternatives decision is fully spelled out rather than implied.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the fallback to the project default when the user has no dashboard, and the return format ('Returns JSON'). It does not describe pagination or error cases, but for a parameterless read tool that is a minor gap.

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 front-loaded sentences, with the core purpose first and usage/return notes after. Slight redundancy between 'landing dashboard' and 'the dashboard you see first when you open the project,' but no sentence is wasted.

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 tool with no output schema, the description covers purpose, fallback behavior, usage condition, sibling relationship, and return format. 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?

The tool takes zero parameters, so the baseline of 4 applies. The description correctly implies a parameterless call by advising use 'when you don't have a dashboard id,' requiring no further argument documentation.

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 your landing dashboard, or the project default if you have none') and clarifies scope by likening the detail level to `dashboards_get`. An agent can distinguish this from dashboards_get and dashboards_list without opening another 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?

Provides an explicit selection condition ('Use it when you don't have a dashboard id') and names the sibling that governs the alternative behavior ('change which dashboard you land on with `dashboards_set_home`'). Nothing about when to pick this over its siblings 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 destructiveHint=true and readOnlyHint=false, and the description goes well beyond them: it explains exactly what is overwritten (the project default), what is preserved (the source dashboard), who is affected (new users and anyone without a home dashboard), the admin requirement, and that it needs user confirmation.

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?

Front-loaded with the action and constraint, and every sentence carries operational weight. The clause explaining what the default is slightly restates the opening sentence, a minor redundancy in an otherwise tight four-sentence definition.

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 destructive admin tool with no output schema, the description covers everything an agent needs: effect, scope, side effects, permissions, confirmation guidance, and the sibling alternative. 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?

Schema coverage is 100% and the schema already tells the agent the id is a dashboard ID discoverable via dashboards_list. The description only implicitly clarifies that the id refers to the source dashboard being copied rather than the target, 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 (copy a dashboard onto the project default) plus scope (new users' starting dashboard) and an access gate (administrators only). It is unmistakably distinct from siblings like dashboards_set_home, dashboards_update, and dashboards_create.

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 names the alternative for a closely related goal: 'To change only your own landing dashboard, use dashboards_set_home.' It also states the admin-only prerequisite and warns to confirm with the user before running, so both when-to-use and when-to-avoid are covered.

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 only flag destructiveHint=true generically; the description sharpens the blast radius by stating that 'everything else on the dashboard stays as it was' and that the underlying chart 'is kept and can be added back'. That non-destructive-to-the-chart nuance is the exact behavioral detail an agent needs and cannot derive from the hints alone.

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?

Front-loaded with the action, then scope, then alternatives, then the safety warning — a good ordering. 'Returns JSON' is low-value filler that repeats what is implied and slightly dilutes an otherwise tight passage.

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 two-required-parameter mutation with no output schema, the description covers action, preservation semantics, id sourcing, alternative tools, and a user-confirmation caveat. No output schema exists, so it needn't describe return values, and 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?

Schema description coverage is 100% and both parameters are already documented in-schema. The description's 'Get widget ids from `dashboards_get`' adds a mild pointer to where ids come from, but otherwise the schema carries the parameter semantics — baseline 3.

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 first sentence names a specific verb and resource ('Remove a widget from a dashboard'), and the body distinguishes this from adjacent operations by naming `dashboards_add_chart` (re-add) and `charts_delete` (delete the chart entirely). An agent can pick this tool over its siblings 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?

It gives explicit routing: use this to detach a widget, use `charts_delete` 'only to remove the chart from the project entirely', and use `dashboards_get` to source ids. It even states a prerequisite workflow (confirm with the user before running) — nothing 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 flag the destructive mutation. The description adds crucial context: it replaces your previous home, affects only your own landing dashboard, leaves other users unaffected, and recommends confirming with the user. This scope-of-effect detail goes beyond the annotations and is exactly the kind of behavioral context needed.

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?

Front-loads the purpose in the first sentence and follows with scoping, alternatives, and a safety note. The sentence 'Returns JSON' is minor filler, but overall structure is efficient with no major 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?

Given the tool is destructive (annotations cover this), takes one fully-described parameter, and has no output schema, the description supplies all additional information an agent needs: exact effect, user-scope, alternatives, and a confirmation warning.

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%, with the sole parameter 'id' fully documented in the schema, including where to find it. The description does not add anything 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?

States a specific verb and resource: making one of your dashboards your landing dashboard. It explicitly distinguishes from siblings by naming dashboards_promote_to_default for changing the default new users start from.

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 explicit when-to-use guidance, including the alternative tool for a different use case (dashboards_promote_to_default) and a validation step via dashboards_mine. Also advises checking with the user before running due to its destructive nature.

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 and destructiveHint=true, but the description adds non-obvious details beyond them: widgets absent from a new list are removed, only the owner can change sharing, and the response is JSON. It stops short of describing permissions needed for other fields or how partial updates interact with untouched fields.

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?

Well front-loaded: the capability and the destructive consequence come first, then alternatives, then the confirmation warning. The first sentence and the following 'Changes a dashboard's name, description or sharing...' clause partially restate each other, a mild redundancy in an otherwise efficient block.

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 destructive mutation tool with no output schema, the description supplies the safety-warning, ownership constraint, alternative routing, and the replace-vs-add semantics. With annotations and full schema coverage in place, nothing material 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 coverage is 100%, so the schema already documents each parameter; baseline is 3. The description adds consequence-level meaning for `config` (whole-list replacement and silent removal of omitted widgets) and the owner-only restriction on sharing, which helps an agent reason about the call rather than just the syntax.

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?

Opens with specific verbs and resource: rename a dashboard, change its visibility, or replace its widgets and layout. It also explicitly distinguishes itself from dashboards_add_chart and dashboards_remove_widget by contrasting 'replace its whole widget list' with 'add or remove one chart'.

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?

Names the alternative tools and the exact condition that selects them ('To add or remove one chart, use `dashboards_add_chart` or `dashboards_remove_widget`, which keep everything else'). It also adds a prerequisite/confirm step: check with the user before running it because it changes or deletes existing data.

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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context beyond that: it is a dry-run that does not save, and it returns JSON. It stops short of detailing response shape or any auth/limit behavior, but with annotations carrying the safety profile this is solidly above baseline.

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 core action and scope. Every clause carries routing information or a behavioral constraint; nothing is redundant.

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 multi-mode preview tool with readOnly annotations and no output schema, the description covers the supported widget types, the two invocation modes, the routing to add/update/data siblings, and the return format. An agent has everything needed to call 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 coverage is 100%, so the baseline is 3. The description goes further by mapping the two usage modes to parameters: a saved chart is previewed by id ('chart'), while list, materialised view and markdown widgets are previewed via their config, which clarifies how 'chart' and 'config' relate.

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 ('Show') and resource ('the data a widget would draw') and immediately clarifies the non-persistent preview scope. It names the sibling tools it is not (dashboards_data, dashboards_add_chart, dashboards_update), so an agent can disambiguate 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?

Explicit when-to-use: to see what a saved chart shows now, or to try a widget before persisting it. It names the alternative 'dashboards_data' for widgets already on a dashboard and ties add/update flows to dashboards_add_chart and dashboards_update. Nothing 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 cover the safety profile (readOnly=false, destructive=false). The description adds genuine behavior beyond them: it returns the created record with its new id, auto-stringifies objects/arrays for jsonb fields, and discloses that EntityCreated workflows will fire — a meaningful side effect an agent should know.

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?

Front-loaded with the core action, then consequences and the sibling route. No filler sentences — each one (id return, jsonb coercion, workflow trigger, bulk alternative) 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 2-parameter create tool with no output schema, the description covers the payload format, return shape, side effects, and the bulk-load escalation path. 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the data payload is a JSON map of field names to values and that jsonb objects/arrays are auto-coerced to JSON strings, adding real semantic value for the 'data' parameter.

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 (create) and resource (record), and clarifies it inserts exactly one record from a JSON object and returns it with a new id. It distinguishes itself from siblings like data_import, data_update, and data_delete without the agent needing to open 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?

Explicitly routes bulk loading to the alternative: 'To load many rows from a file, use `data_import`.' This gives a clear condition for choosing a sibling, though it doesn't spell out other when-not cases (e.g. via API vs file).

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?

Even though annotations already declare destructiveHint=true and openWorldHint=false, the description adds substantial context an agent could not infer: related records cascade via the relationship field's on-delete rule, and EntityDeleted-triggered workflows will fire. It also surfaces the confirm-with-user expectation.

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?

Front-loaded with the action, then layers cascade, workflow, and safety notes in tight sentences. Every sentence carries information, though the four-sentence block is slightly dense for a two-parameter deletion tool.

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?

No output schema exists, but for a destructive delete the description covers the effects that matter: what is removed, what cascade consequences follow, what side effects (workflow triggers) occur, and the required user confirmation. 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 coverage is 100%, so the schema already documents both parameters (id even tells you to find it with data_list). The description reinforces that the id is numeric but adds little meaning beyond what the schema provides, 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 (delete) and resource (one record, identified by numeric id, within an entity), and the cascade/workflow sentences make the scope concrete. An agent can tell this apart from sibling delete tools like entities_delete or files_delete without opening a schema, because the resource is a data record reached through an entity name.

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?

Usage is implied by the family naming (data_list/data_create/data_update/data_delete) but never stated, and no alternative is named for the case where you actually want to remove a schema or a file. The only guidance is the caution to confirm with the user before running, which is a safety instruction rather than routing.

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=false, openWorldHint=false, and the description adds real side-effect context: streamed page-by-page fetching, writing to a local file or stdout with '-', and the overwrite guard ('won't overwrite an existing file unless forced'). It omits any permission/auth requirements or practical limits, so it is strong 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.

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

Four sentences, front-loaded with the core action and formats, then the caveats. Slightly redundant phrasing of 'streamed page by page' / 'fetching page by page' in the first two sentences, but otherwise every clause carries 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 an 8-parameter export tool with no output schema, the description covers formats, filtering, field selection, overwrite behavior, and streaming. The only meaningful gap is the absence of auth/permission or throughput expectations; the destination and result (a file or stdout) are otherwise well explained.

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 baseline is 3, but the description adds meaning not in the schema: one-to-many fields are omitted unless explicitly named in the field list, and format defaults derive from the file extension. These are behavioral rules about the parameters rather than restatements.

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 records) plus the output formats (CSV, JSON, JSONL), and explicitly distinguishes itself from the sibling data_list. An agent can identify this as the bulk/paged export tool 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?

Gives an explicit routing rule: 'For one page of records, use data_list,' which is the exact counter-condition for this tool. It also tells the agent the filter syntax matches data_list, so filters can be reused without re-learning.

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=true and openWorldHint=false, so the safety profile is covered and the bar is lower. The description adds genuine value by disclosing the return shape ('all of one record's field values') in the absence of an output schema, and signals an access-control dimension by pointing to data_rls. It stops short of describing not-found/denied behavior, so it is not 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?

Two sentences, front-loaded with the core action, then a compact routing clause. Every clause earns its place and nothing is repeated padding.

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?

No output schema exists and the description compensates by stating what is returned; annotations cover the read-only safety profile and the required entity/id pair is documented in-schema. Minor gap: nothing about error behavior for a missing id or an RLS-denied record, which is relevant given the data_rls reference.

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 both parameters are documented in-schema (including how to find the id), so the baseline is 3. The description only echoes the schema ('numeric id') and adds no format, range, or entity-name guidance 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?

States a specific verb and resource ('Get a single record by ID') and immediately clarifies the lookup key ('numeric id'), which separates it from the list/search siblings. It also names the sibling tools it is not, so an agent can route 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?

Explicitly gives the conditions for the alternatives: use data_list with a filter when the id is unknown, search_query for text lookup, and data_rls for access/permission questions. This is a complete when-to-use / when-not-to-use routing block rather than an implied hint.

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 only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the description carries the rest and does so well: it reads a local file, creates one record per row, validates against field types, rejects unknown columns unless ignore_unknown is set, ignores system columns, and never updates existing records. That is substantial behavioral context beyond the annotations.

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

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

Four tightly packed sentences with the safety protocol front-loaded and no filler. Minor friction: it references a '--yes' flag that has no corresponding schema parameter, which could momentarily confuse an agent mapping prose to inputs.

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 7-parameter mutation tool with no output schema and only safety annotations, the description covers the important semantics: validation, row rejection, system-column handling, and the mandatory dry-run flow. The only gaps are the concurrency setting and the errors-file return behavior, which are minor for a create-only import.

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%, so baseline is 3. The description does add meaning for a few parameters (dry-run validation, dropping unknown columns, format inference), but it never mentions concurrency or the errors output-file behavior, so it does not meaningfully exceed what the schema already documents.

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?

Opens with a precise verb and resource ('Create records from a CSV, JSON array or JSONL file') and immediately scopes the operation as bulk/one-record-per-row. It also names the sibling it is not ('For a single record, use data_create'), so an agent can route between the two 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 procedural guidance ('Always run with --dry-run first and only add --yes after the dry run is approved') plus an explicit alternative for the single-record case (data_create). Both the when-to-use and the when-to-use-something-else cases are covered.

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=true and openWorldHint=false, so safety is covered. The description usefully adds pagination behavior (one page, 20 by default) and the filter syntax, though it does not explain how 'all' streaming interacts with 'limit' beyond what the schema states.

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?

Four tight sentences, front-loaded with the core action and pagination, then filter syntax, then the sibling routing. Zero waste.

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 list tool, the description covers scope, return format ('Returns JSON'), pagination default, filter syntax, and alternative tools. With annotations carrying the safety profile and no output schema to explain, nothing an agent needs is missing.

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