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

With no annotations, the description carries the full burden. It discloses the visibility scope ('visible only to the caller until submitted') and the intended lifecycle, which goes beyond a simple creation action. It doesn't mention errors or side effects, but it does convey the non-destructive nature and the submission path.

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 a single, well-structured paragraph that front-loads the core purpose, then flows into parameter semantics and workflow. Every sentence adds value—no fluff, and it's concise yet detailed.

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

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

For a tool with no annotations or output schema, the description covers purpose, parameters, and usage workflow. It doesn't mention return values or error conditions, but it provides enough for an agent to correctly invoke the tool, especially with the guidance to validate config via run_explore_query.

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 0%, so the description must explain parameters. It does so for dashboard_kind (with the two values), target_domain_key (matching the dataset domain), and config_json (configuration for the kind, built via run_explore_query). Title is self-explanatory, so the description effectively compensates for the schema's lack of detail.

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

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

The description opens with a clear verb+resource: 'Create a new draft report in the caller's personal workspace.' It distinguishes itself from siblings by stating the visibility scope and by explaining the two dashboard_kind variants, making it unambiguous which tool to use.

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 provides explicit context for when to use the tool (creating a draft) and a recommended workflow: build config_json by test-running with run_explore_query. It doesn't explicitly state when not to use it (e.g., for updates), but the sibling list and the word 'create' imply that distinction. This is strong guidance for parameter preparation.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool fetches metadata, which implies a read operation, but it does not disclose whether the report must be in a certain status, whether config_json is returned in a particular format, or what happens if the report_id does not exist. The description adds minimal behavioral context beyond the basic fetch action.

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 a single, focused sentence that front-loads the action ('Fetch a report's metadata') and immediately lists the specific fields returned. Every word earns its place, and there is no redundant or vague phrasing.

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

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

For a simple single-parameter read tool, the description is mostly adequate: it names the resource, the action, and the return fields. However, with no annotations and no output schema, it could be more complete by noting error behavior (e.g., invalid report_id) or any access constraints. The sibling list helps contextualize the tool, but the description itself leaves a few minor gaps.

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 0%, so the description must compensate for the undocumented report_id parameter. The description does not explain what report_id refers to or how to obtain it, but the parameter name is self-explanatory and the tool's purpose makes the parameter's role clear. The description adds some context by listing the returned fields, but it does not clarify the parameter's format or constraints beyond the schema's integer type.

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 clearly states the tool fetches a report's metadata and enumerates the specific fields returned (title, status, dashboard_kind, config_json). It distinguishes itself from siblings like create_draft_report or update_draft_report by focusing on retrieval, though it doesn't explicitly name a sibling alternative.

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 implies a read-only retrieval use case, which is enough to differentiate from mutation siblings like create_draft_report, update_draft_report, and submit_report. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites like the report needing to exist or be accessible.

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 no annotations provided, the description carries the behavioral burden. It states the tool lists datasets and exactly what fields are returned, and adds a critical usage rule about using keys instead of labels, which guards against misuse. However, it does not disclose potential limitations like pagination or sorting, but for a simple list tool this is adequate.

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

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

The description is two sentences with no filler. It front-loads the purpose, then details the output content, and finishes with a practical tip. 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?

Given the tool's simplicity, no parameters, and existence of an output schema, the description covers everything an agent needs: what it lists, what fields are returned, and how to use the results with run_explore_query. Nothing essential is missing.

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

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

The tool has zero parameters, so there is nothing to explain. The description correctly omits parameter details, and the baseline of 4 applies given no parameters exist.

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 clearly states the verb 'List' and the resource 'datasets', scoped to 'the caller's identity can query'. It distinguishes itself from sibling tools like run_explore_query by being about enumeration, not query execution.

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 does not explicitly say when to use this tool vs alternatives, but by mentioning that column keys should be used in run_explore_query, it implies this is a precursor to querying. It lacks explicit exclusions or alternative conditions, so usage is implied rather than stated.

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

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

With zero annotations, the description carries the full burden of behavioral disclosure, and it delivers richly: it states the operation is a non-persistent preview ('never persisted'), discloses the server-side truncation cap ('capped at 500 rows'), and enumerates the return shape (rows, row_count, truncation flag, ranked chart recommendations). This is precisely the behavioral context an agent needs that annotations would otherwise provide.

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?

A single dense paragraph, front-loaded with the core purpose before moving to sourcing, returns, and downstream usage. Every clause earns its place — the truncation cap, the chart-type list, and the cross-reference to report tools are all load-bearing. It is slightly long in one block and could benefit from clearer segmentation, but there is no 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 moderately complex aggregate-query tool with no output schema and no annotations, the description is notably complete: it covers purpose, input sourcing, return values, truncation behavior, and the downstream report-building flow. The principal gap is the unstated query-assembly semantics for measures/dimensions/filters, though the schema's $defs structure partially mitigates that. An agent can call this tool correctly for a basic query and understands the result shape.

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 0%, so the narrative description must compensate for parameter meaning. It explains dataset_key sourcing ('every column value from list_datasets's output'), but it does not explain the aggregate-query construction semantics — how measures, dimensions, filters, bucket, and limit combine to shape the query. The $defs enums (operators, aggs, buckets) are self-explanatory at a structural level, but the description never tells the agent how to assemble a valid aggregate query, which is the core knowledge for this tool.

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 opens with a specific verb+resource: 'Run a live, ad-hoc aggregate query against a whitelisted dataset — a preview, never persisted.' This clearly distinguishes the tool from its siblings — list_datasets (enumeration), the report tools (persistence/build), and the view dashboards (UI surfaces). An agent can tell exactly 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?

The description explicitly tells the agent where to source inputs: 'Pick dataset_key and every column value from list_datasets's output.' It also connects downstream usage — 'use the first recommendation as the visualization.type when building a report section with create_draft_report/update_draft_report.' This orients the agent within the tool workflow. It lacks explicit exclusions ('don't use this for X'), but the preview-vs-persist contrast with report tools implicitly signals when not to use it.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the state transition ('moves it to 'submitted' status') and the visibility effect ('visible to that domain's reviewers'), which is useful. However, it does not mention whether the action is reversible, whether it triggers notifications, or what the response looks like. For a state-changing tool, this is adequate but not rich.

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

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

The description is two sentences with no wasted words. The core action and state change are front-loaded, followed by the visibility effect and access requirement. 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 tool with no output schema, the description covers the action, the state change, the visibility effect, and the access prerequisite. It does not describe the return value, but with no output schema and a simple action, that is a minor gap. The description is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the single parameter. The description implies that report_id identifies the report to submit, but it does not explicitly state that report_id is the identifier of the draft/rejected report. The schema already provides the parameter name and type, so the description adds minimal semantic value beyond what the schema shows. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Submit'), a specific resource ('a draft/rejected report'), and the resulting state change ('moves it to 'submitted' status'). It also names the target audience ('visible to that domain's reviewers'), which distinguishes it from sibling tools like create_draft_report and update_draft_report. This is a clear, non-tautological definition.

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 clearly implies when to use this tool: when a draft or rejected report is ready for review. It also provides a prerequisite ('Requires author-tier access to the report's target domain'), which helps an agent decide if it can invoke the tool. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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

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

With no annotations, the description carries the behavioral burden. It discloses partial-update semantics and the 409 conflict on invalid status, which is valuable. However, it omits other behavioral context such as the response shape, permission requirements, error behavior beyond 409, and whether explicitly passing null clears a field.

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

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

The description is a single tight sentence that front-loads the core purpose, then adds the status constraint and partial-update behavior. Every clause contributes useful information 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 mutation tool with no annotations and no output schema, the description is reasonably complete: it identifies the operation, the applicable statuses, and the update semantics. But it leaves gaps around what the response returns, how null/default values are handled, and what the 409 error implies beyond 'not allowed.'

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 0%, so the description must compensate. The phrase 'Only fields you pass are changed' adds real meaning by clarifying optional title and config_json behave as a partial update rather than a full replacement. Still, it does not explain the contents or constraints of config_json, nor the null-means-unchanged ambiguity.

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 uses a specific verb ('Edit') and resource ('a report') and narrows scope to reports in 'draft or rejected status.' This clearly differentiates it from siblings like create_draft_report, get_report, and submit_report, so an agent can identify the intended operation without opening the schema.

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

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

It explicitly states when the tool applies ('while it's still in draft or rejected status') and warns that the backend '409s otherwise,' which effectively tells the agent when not to use it. It does not explicitly name sibling alternatives for other statuses, but the status gate is clear enough for basic 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?

No annotations are provided, so the description carries the burden. 'View' clearly indicates a read-only operation, and the description adds what the user will see (rows, visualization, insight). It does not disclose behavior beyond that, such as whether the report must be previously saved or whether any side effects occur, but for a view operation this is minimally adequate.

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

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

One concise sentence that front-loads the action and immediately specifies the object and output contents. There is no filler, repetition, or unnecessary detail.

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 tool with no output schema, the description covers the core operation and expected content. It lacks explicit usage guidance and parameter semantics, but the low complexity keeps the definition reasonably complete.

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?

With schema description coverage at 0% and no parameter explanation in the description, report_id is only documented by its schema title and type. The description references 'a saved report' but does not add meaningful semantics about the identifier or how it should be obtained, so it fails to compensate for the schema gap.

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 uses a specific verb ('View') and names a distinct resource ('saved single-query custom_query report'), then enumerates what is returned: rows, chosen visualization, and a Claude-generated insight. This clearly differentiates it from siblings like view_report_builder_dashboard and get_report.

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 phrase 'saved single-query custom_query report' implies this tool is for viewing an existing report rather than building or running one. However, it does not explicitly state when to choose this over get_report or view_report_builder_dashboard, nor does it mention any exclusions.

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 no annotations, the description must carry the behavioral burden. It discloses the return content (all section rows plus one synthesized insight) and access scope, but does not explicitly state that the operation is read-only or free of side effects. The word 'view' implies no mutation, but it is not explicit, and there is no mention of error behavior or performance. This is adequate but not comprehensive.

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

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

The description is two sentences, front-loaded with the primary function and then adding access conditions. Every word earns its place, with no fluff or redundancy. It is efficiently structured and easy to parse.

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 tool with no output schema, the description covers the essential return format (all rows plus insight) and access requirements. It does not discuss error cases or pagination, but these are not critical for a simple view tool. It is reasonably complete, though it could mention what happens if the report is not found.

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 schema has 0% description coverage for the only parameter (report_id). The tool description does not explain what report_id is or how to obtain it, beyond the context that it identifies a report. Since the parameter name is self-explanatory, the description adds minimal value. With low coverage, the description should compensate but does not.

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 clearly states the tool's purpose: viewing a saved multi-section report_builder report, including all rows and a synthesized insight. It specifies the exact resource (report_builder report) and distinguishes from siblings like view_custom_query_dashboard by emphasizing 'report_builder' and the insight synthesis. The access conditions further clarify scope.

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 provides access conditions (draft owned or published with Readonly access) but does not explicitly guide when to use this tool versus alternatives like get_report or view_custom_query_dashboard. It implies usage for report_builder reports but lacks direct comparisons or exclusions. The access note is useful but not comparative.

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