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

With no annotations, the description carries the full burden and meets it: it discloses that the dataset must belong to the same template's project, that rendering is asynchronous so the job id returns before the PDFs exist, and — critically for a mutation-style side effect — that filename_template and group_by are 'saved onto the template/project, so they change the defaults for later runs, not just this one.' That persistence warning is exactly the kind of hidden consequence annotations would otherwise supply.

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 purpose and the sibling contrast are front-loaded, and the numbered workflow is scannable. It is on the long side and the 'SheetRender turns HTML templates plus spreadsheet rows into rendered PDFs' framing sentence is partly scene-setting, but the remaining sentences each carry routing or constraint 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?

Despite no output schema, the description tells the agent what comes back (a job id), how to get the results (get_job polling, get_document downloads), and what preconditions must hold (dataset in the same project). For a 4-param tool with no annotations, 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. The description goes beyond it by explaining that column names must be sanitized keys ('Invoice No' becomes invoice_no) reported by create_dataset/upload_dataset/list_datasets, and that these two params persist as project defaults — details found only in prose, not in the schema strings.

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 opening states a specific verb and resource: 'queues a batch job that renders one PDF per row of a dataset, and returns the job id.' It explicitly contrasts with the sibling render_template ('rather than calling render_template in a loop'), so an agent can distinguish batch from single-render 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?

It gives a concrete usage condition ('when the user wants many documents at once — an invoice for every row, one letter per employee'), names the alternative to avoid, and lays out the full 5-step workflow with which sibling produces each required id. It also states when NOT to pass the optional params: 'Only pass them when the user asked to change how output is named or grouped.'

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 full burden and does so richly: it discloses the flat-array/flat-object shape requirement, union-of-keys header semantics with missing keys becoming blanks, scalar-only value rules, rejection of NaN/Infinity/values past 2^53, the 50,000-row and 500,000-cell caps, that creation is free (only rendering is billed), and that the dataset is attached to the template's project and reusable by later jobs.

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 constraints, then limits, then return semantics in a logical order. It is on the long side and the opening 'SheetRender turns HTML templates...' line is arguably ambient context, but every paragraph earns its place by resolving a real ambiguity.

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 (dataset id plus per-column sanitized keys) and warning that the sanitized key is what the template must reference. Combined with the limits, cost model, and placement rules, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining the union-of-keys header derivation, the exact-number caveat (send large integers as strings), and that the returned sanitized `key` — not the original header — is what placeholders, filename_template and group_by address. That is meaningful semantics the schema does not carry.

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 ('turns rows ... into a dataset') and immediately distinguishes itself from siblings by naming upload_dataset and list_datasets with the conditions that select them. 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?

Explicit when-to-use ('the normal way to start a batch', with the user-intent example 'an invoice for each of these clients'), plus explicit when-not with named alternatives: upload_dataset for data already on disk, list_datasets for an existing dataset. 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?

With no annotations the description carries the full load, and it delivers real behavioral detail: a 3-minute wait, 10 MB size cap, accepted formats (CSV/XLSX for data; PDF/PNG/JPG/WebP/DOCX for examples), and the returned fields (status, template id, mapping, preview URL). It does not mention permission/auth requirements, nor explicitly flag that this persists a new artifact, which is the main gap for a mutation tool with zero annotation coverage.

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?

Key constraints (the exclusive-or data source and the example/brief rule) are front-loaded, and every sentence carries a constraint, limit, or return value. It is dense to the point of being run-on in places, but there is little wasted text.

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 12-parameter tool with no annotations and no output schema, the description is unusually complete: it covers input combinations, file types, size limits, latency, and enumerates the return values. Remaining gaps are auth/permission expectations and the meaning of the returned 'design status'.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the exclusive-or relationship among data sources and the 'example alone' vs 'brief with optional style_id' rule. data_path/example_path are also framed as local-file alternatives to their base64 counterparts, which the schema treats as independent fields.

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 ('Design a saved template') and immediately scopes exactly what inputs produce that template, so an agent knows this creates a persisted template rather than rendering one. It never names or distinguishes itself from nearby siblings such as render_template or get_design, so sibling differentiation is left to inference.

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 composition rules: data must come from exactly one of dataset_id / inline rows / data_base64+data_filename, and the design source is 'an example alone, or a brief with optional style_id.' That is clear when-to-use guidance for the parameter combinations. It stops short of saying when NOT to use this tool or when to prefer render_template instead.

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 full behavioral burden. It usefully discloses conditional return behavior — that template id, name, mapping and preview URL only appear once the design is complete — but says nothing about the not-yet-complete case (pending status, errors), auth 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?

A single front-loaded sentence that leads with the primary output (status) and then qualifies the conditional extras. No filler or redundancy.

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

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

There is no output schema and no annotations, so the description is the only source of return-shape information. It names the returned fields but does not enumerate possible status values or explain the incomplete-state response, leaving a meaningful gap for a status tool.

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

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

Schema description coverage is 100% and the schema already states design_id is 'Design id returned by design_template.' The description adds no further meaning about the id's format or provenance, 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?

The description names a specific verb (Get) and resource (a design), and even enumerates the payload it returns (status, template id, name, mapping, preview URL). It does not distinguish itself from siblings like design_template or get_job, so an agent must infer that design_template is the producer and this is the status poller.

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 'when complete' implies this is a polling/status-check tool rather than a fetch of a finished artifact, which gives implied usage. However, it never states when to call it versus design_template, render_template, or get_job, and gives no polling cadence or terminal-condition guidance.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the return includes a temp-file path and size, that PDFs under 512 KB are attached inline, and warns about performance when fetching many documents. It also notes the provenance of document_id. While it doesn't mention error handling or permissions, it covers the essential behavior for a download 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?

The description is well-structured: the first sentence states the core purpose, followed by id provenance, usage guidance, and return behavior. Every sentence adds value with no fluff, and the most critical information (spoiler: the id source) is front-loaded.

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 tool with one parameter and no output schema, the description covers all necessary aspects: what it does, how to obtain the id, when to use it vs alternatives, and what the return includes. Nothing essential is missing 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 schema already describes document_id with high coverage, but the description adds crucial disambiguation: it explains the id comes specifically from get_job's document list and clarifies it is not a template or job id. This goes beyond the schema's baseline, making parameter meaning clearer for the agent.

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 the specific verb (download), resource (PDF from a batch job), and distinguishes it from siblings like render_pdf and get_job. It also clarifies that document_id comes from get_job, making the tool's role 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 states when to use the tool (fetch a specific document or spot-check a batch) and when to instead direct the user to the SheetRender web app for bulk downloads. It also references get_job for obtaining valid IDs, providing clear usage 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?

With zero annotations, the description carries the full behavioral burden and succeeds. It discloses the asynchronous polling nature, enumerates the complete state machine (queued, retry_queued, running, succeeded, partial, failed, cancelled), explains that the document list is empty during in-progress states, and specifies what becomes available once finished. This is exactly the behavioral context an agent needs to avoid misinterpreting empty results.

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

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

Three short paragraphs, zero filler. The purpose and polling caveat are front-loaded; the SheetRender context sentence and the get_document routing both earn their place. The state enumeration is necessary, not redundant, given the target states versus document-list-availability states must be distinguished.

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?

Despite having no output schema and no annotations, the description fully compensates: it explains the returned fields (status, rows done/failed, document ids/filenames), the conditional availability of results, and the follow-up action. For a single-parameter polling tool, 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% — job_id is documented as 'Job id returned by create_batch_job.' The description reinforces but does not extend this: it references 'the id' of every rendered document but adds no new formatting or validation details beyond the schema. Baseline 3 is appropriate since the schema already carries the semantic weight.

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+resource: 'reports the progress of a batch job started by create_batch_job' — it monitors a job rather than producing content. It distinguishes itself from siblings by explaining the workflow position (reports on create_batch_job output, feeds get_document). The title 'Check a batch PDF job' reinforces the purpose without ambiguity.

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 prerequisite sibling (create_batch_job), the successor (get_document for downloading), and gives explicit call-timing guidance: poll again while status is in 'queued', 'retry_queued' or 'running' rather than treating an empty document list as zero results. This is concrete, actionable when-to-use guidance that maps the tool into a larger workflow.

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 full disclosure burden, and it delivers non-obvious behavior: results are project-wide rather than restricted to the template, ordered newest first, and include id, row count and column keys. It stops short of stating pagination/result limits or whether the operation is purely read-only, so the safety and volume profile is still partially inferred.

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 what the tool is and what it returns before moving to usage and the column-key tip; every sentence carries information. It runs to three paragraphs where two would suffice, but 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?

No output schema exists, so the description must describe returns itself — it does so explicitly (id, row count, column keys) plus ordering and scope. For a single-parameter list tool, an agent has everything needed to call and interpret it.

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 one parameter with 100% schema description coverage, so the schema already documents template_id and its provenance (from list_templates). The description adds domain context about what the id scopes but no format or syntax detail beyond the schema, making the baseline 3 appropriate.

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

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

States a precise verb and resource ('lists the datasets a batch job can render with a given template') and pins down scope: everything in that template's project, newest first, with id, row count and column keys. That is enough to distinguish it from create_dataset, upload_dataset and list_templates without opening any schema.

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

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

Gives an explicit triggering condition ('when the user refers to data they have already loaded') plus a second concrete use case (re-running a batch over an existing dataset instead of duplicating). It also names the alternatives to use when nothing fits — create_dataset or upload_dataset — so routing decisions are fully determined.

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 full burden; it discloses that the operation is a read ('lists'), is scoped to the user's account, and returns templates together with their ids. It is silent on ordering, result size/pagination, and account/permission requirements, which keeps it short of a 5 for an un-annotated 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?

Effectively front-loaded: the domain context comes first, then the action, then the routing guidance. The closing 'Takes no arguments' is mildly redundant against the empty schema, and the middle sentence is long, 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?

Given a no-arg, annotation-free, no-output-schema listing tool, the description supplies the essential context: what it returns, why it exists, and when to call it. Some return-value detail (ordering, size limits) is absent, which is the only real 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?

The tool takes zero parameters, so the schema baseline is 4; the description reinforces this with 'Takes no arguments.' No additional parameter meaning is needed or missing.

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 precise verb+resource ('lists the templates saved in the user's account, with the id each one needs') and separates itself from siblings by noting that create_dataset and list_datasets take a template_id instead. The opening sentence even establishes the SheetRender domain so the agent understands what a template is here.

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 an explicit trigger condition ('Call it first whenever the user refers to a template by name') plus the concrete alternative behavior it enables: mapping a name to an id that 'every other tool here takes'. This is a clear when-to-use rule with the tool's role in the workflow 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?

With no annotations provided, the description carries the full burden. It transparently discloses that external resources are not fetched, that HTML over 2MB is rejected (including after substitution), that free accounts get a footer, and that return includes path/size plus inline attachment for small PDFs. This exceeds expectations for behavioral disclosure.

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

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

The description is well-structured with clear paragraphs. Each sentence earns its place: purpose, usage (with alternative), HTML requirements, data behavior, server limits, and return format. It is detailed but not repetitive; complexity is handled without bloat.

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?

The description covers all necessary aspects for correct use: input requirements, template variable mechanics, output behavior, error conditions (2MB limit), and an environmental quirk (free-plan footer). It is fully self-sufficient even without annotations or output schema.

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

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

Despite 100% schema coverage, the description adds substantial meaning beyond the schema: it explains Jinja variable substitution with a concrete example, confirms loops/conditionals work, clarifies that data can be omitted, and details page_settings usage in plain terms. This significantly aids correct invocation.

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 function: rendering a single PDF from user-supplied HTML and returning the saved file path. It also distinguishes itself from render_template by explicitly saying when to use which, making it easy for an agent to select correctly.

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

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

The description provides explicit guidance on when to use this tool ('one-off documents... writing the markup yourself') and when to use the alternative (render_template when a saved template exists). It also warns about size limits and the free-plan footer, covering both usage context and potential pitfalls.

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 full burden and does so: it discloses the free-plan watermark ('expected, not a bug'), the return payload (temp-file path and size, inline attachment under 512 KB), and the override semantics of page_settings. These are behaviors an agent cannot infer from the schema and would otherwise be surprised by.

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 short paragraphs, each doing distinct work: what it does, when to use it vs alternatives, what data means, and the page_settings override plus return/watermark notes. Front-loaded with the core purpose and no filler sentences.

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 three parameters, nested objects, and no output schema, the description covers selection, sibling routing, the single-row constraint, override behavior, and the return value including the free-plan watermark. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents data as Jinja variables and page_settings fields, making 3 the baseline. The description adds genuine meaning beyond the schema by stating that `data` supplies exactly one row's worth of values and that omitting page_settings preserves the template's saved setup while passing it overrides only for this render.

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 ('renders one PDF from a template already saved in the user's account') and explicitly contrasts with the sibling render_pdf ('Use render_pdf instead when you are writing the HTML yourself'). An agent can distinguish this from render_pdf, design_template, and create_batch_job 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?

Names the conditions for use ('when the user wants a document in their existing design'), the source of the required id ('Get `template_id` from list_templates'), the alternative tool for a different case (render_pdf), and the escalation path for multi-row output (create_batch_job after create_dataset/upload_dataset). This is explicit when/when-not/alternatives coverage.

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

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

No annotations are provided, so the description carries the full burden and meets it: it discloses that file_path is on the user's machine rather than SheetRender's, that the first row must be the header, which formats are rejected, the 20 MB / 500,000-cell limits, and the billing nuance (upload free, rendering counts against the plan).

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 separated paragraphs for usage, parameter semantics, limits, and return values. Length is justified by the amount of genuinely useful constraint information, and no sentence is 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?

Though no output schema exists, the description describes the return values (dataset id plus each column's sanitized key) and covers the limits, format restrictions, and machine context an agent needs 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 schema already documents both parameters. The description still adds real meaning beyond it: file_path lives on the user's machine, its format constraints and limits, and that the returned key is the sanitized name used by placeholders, filename_template, and group_by.

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 ("uploads a local .csv or .xlsx file as a dataset a batch job can render") and explicitly contrasts with the sibling create_dataset. An agent can tell this apart from create_dataset 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 an explicit when-to-use trigger ("when the user points at a file they already have") plus a named alternative and its selecting condition ("Use create_dataset instead when you are holding the rows as JSON"). 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.