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

With no annotations, the description carries the full burden and does well: it discloses that the row count requires a full scan on CSV/JSON but comes from metadata for Parquet, and that column types are DuckDB's auto-detected types (which is what SQL will see). It does not state the read-only/error behavior or what happens with an invalid path, but the cost and type-fidelity disclosures are genuinely valuable.

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 output shape and main use case are front-loaded in the opening sentence, with path semantics and scan-cost caveats following in short, purposeful lines. 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?

An output schema exists, so return values need no explanation, and the cost and type caveats are covered for a read-only inspection tool. The one real gap is the undocumented `sample_rows` control, which an agent must guess at.

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 both parameters, and it covers `path` well (relative to an allowed folder as `list_files` shows it, or absolute inside one). It never explains the `sample_rows` parameter — not its name, default of 5, or whether 0 disables sampling — leaving one of two parameters fully undocumented.

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 gives a specific verb and resource: it shows a file's schema (column names and types), row count, and sample rows. That is clearly distinct from a raw query tool, but it is not differentiated from the overlapping siblings `sample_file` and `profile_file`, which the description never mentions.

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?

"Use this before writing a query, to get exact column names" gives a clear trigger condition for choosing this tool. However, it never names an alternative or a when-not-to-use case, even though `profile_file` and `sample_file` sit right next to it in the sibling list and appear to overlap.

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 supplied, the description carries the safety burden and does so: it declares the operation read-only, states it is time-limited, and warns that analyze=true actually executes the query (a real cost/side-effect disclosure) while returning timings and row counts. What it omits is the concrete time limit and any error/failure behavior, 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 short sentences, front-loaded with the core action and scope, then motivation, then the analyze=false/true distinction. Nothing is padding; even 'still read-only, still time-limited' adds reassurance tied to the executing mode.

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?

An output schema exists, so return values need not be described, and the description covers the essential behavior for a two-parameter read/explain tool. Gaps are minor: no statement of the actual time limit, and the 'file naming' reference assumes familiarity with the file-oriented siblings.

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 compensate and largely does: analyze=true is explained with its exact effect (executes the query, adds per-operator timings and row counts) and its default-off implication. The `sql` parameter gets only the indirect hint 'Same SQL rules and file naming as `query`', leaving the expected SQL dialect/statement form partly inferred from a sibling.

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 ('Show DuckDB's execution plan for a SELECT query') plus the key scope qualifier ('without returning its rows'), which cleanly separates it from the `query` sibling that does return rows. An agent can pick between them without opening a schema.

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

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

Gives concrete when-to-use contexts ('check whether a filter is pushed down into a Parquet scan, or why a query is slow') and implicitly routes row-fetching to `query` via 'without returning its rows'. It lacks an explicit when-not-to-use statement or a pointer naming `query` as the alternative action, so it falls short of a 5.

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

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

With no annotations supplied, the description does real work: it discloses supported formats, the .gz variant, that paths are relative to an allowed folder, what metadata is returned (type, size), and a hard result cap of 500 files. It never states read-only/safety semantics implicitly assumed by 'list', but nothing is misleading.

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 format list, then return shape, then the workflow instruction, then the parameter detail. Every sentence adds usable information and none restates the title or name.

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?

An output schema exists, so return values needn't be spelled out, yet the description still previews path/type/size and the 500-file truncation limit that an agent must know to interpret results. For a one-parameter, non-destructive discovery tool, 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.

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

Schema description coverage is 0%, so the description carries the full burden for `pattern`, and it does: a case-insensitive glob applied to the path, with two concrete examples ('*2024*', 'logs/*.json'). It omits what the empty default does, which is the only meaningful 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?

States a specific verb and resource ('List the data files you can query'), enumerates the supported formats, and positions itself in the workflow with 'Use this first', which implicitly distinguishes it from downstream siblings like profile_file, sample_file, describe_file and query.

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

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

Gives clear when-to-use guidance ('Use this first') and explains the payoff ('those paths can be used directly in SQL, e.g. SELECT * FROM ''sales.csv'''), which is exactly the routing information an agent needs. It stops short of naming alternatives or exclusions, e.g. that an already-known path makes this call unnecessary.

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 burden and does disclose real behavioral traits: full-file scan cost, risk of hitting the time limit on very large files, and the default 50-column cap. It does not state permissions/side-effect profile or that the distinct count is an estimate beyond the parameter naming, leaving a modest 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?

Front-loaded with the output contract, then usage, then a performance caveat — three sentences, each carrying distinct information. 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?

With an output schema present, the description needn't restate return values, and the column-limit behavior plus the timeout caveat cover the main invocation risks. Minor omissions: supported file formats/locations and whether the scan is read-only are not stated, but nothing critical to calling 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 0%, so the description must compensate, and it does for the non-obvious parameter: `columns` restricts profiling to named columns, otherwise the first 50 are used. `path` is left unexplained but is self-evident for a file-profiling tool. Low param count keeps the residual gap small.

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 precise verb+resource ('Profile each column of a file in one pass') and enumerates exactly what is computed: type, null %, approximate distinct count, min, max, average, median, top three values. That is far more specific than a title restatement. It lacks an explicit contrast with siblings like describe_file or sample_file, so it falls short of the top band.

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?

'Use it to spot data-quality problems (many nulls, constant columns, odd ranges) before analysing' gives a clear triggering context. The large-file caveat with the fallback ('profile fewer columns') adds actionable guidance. No explicit when-not or named alternative is given, which keeps it out of the 5 band.

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 and does it well: it enumerates rejected statement types (INSERT, CREATE, COPY, ATTACH, INSTALL, SET, PRAGMA, URLs, out-of-scope paths), discloses the server row cap default of 1000 with a TRUNCATED notice, and warns of a query time limit. Gaps remain: the time limit is unquantified and error/failure semantics (what the agent sees when a query is rejected) are not described.

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 ordered by what an agent needs next: allowed syntax, rejection rules, output/truncation behavior, and strategy advice. Sentence count is high but each one carries a distinct constraint or affordance; nothing merely restates the name or 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?

An output schema exists, so return value structure needn't be spelled out, and the description still covers formatting and truncation. It is nearly complete for a query tool; the missing pieces are error/retry behavior and any note on whether the row cap can be raised.

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 and does: it explains that format='csv' or 'json' is more compact for big results, and that max_rows can be set smaller to see less against a 1000-row default cap. For the required sql parameter it supplies dialect, allowed statement forms, and file-reference syntax (read_csv, read_parquet glob, read_json_auto, quoted table names).

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 and execution engine ("Run one read-only SQL statement (DuckDB dialect) over the data files"), so an agent knows exactly what this does versus profiling, sampling or explaining. It also names sibling context (list_files for folders) that anchors the tool in the toolset.

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

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

Gives strong when-to-use guidance: prefer aggregation with GROUP BY/COUNT/SUM over fetching raw rows, and "use describe_file first for column names" is an explicit prerequisite step. It stops short of routing to explain_query, sample_file or profile_file for cases where this tool is the wrong choice.

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 does real work: it discloses that mode='random' scans the entire file, which is a substantial cost signal an agent would otherwise miss, and frames the tool as cheaper than describe_file. It does not state that the tool is strictly read-only or what happens with files that cannot be parsed, so a small gap remains.

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

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

Three short sentences, front-loaded with the purpose and mode semantics before the cost comparison. Every clause carries information; there is 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?

An output schema exists, so return values need not be described, and the definition covers the mode cost tradeoff and the rows bound. What is missing is whether head mode truncates a large file or whether sampling errors out on unreadable files, which would matter for a three-parameter data-inspection 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 0%, so the description must compensate, and it largely does: it defines the meaning of both enum values for mode and states the inclusive bounds for rows (1 to 100). Only path is left unexplained, which is a minor omission given its obviousness.

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 plus resource ('Show a few rows of a file') and immediately disambiguates the two operating modes, head vs random. It also names the sibling tool it is not (describe_file), so an agent can distinguish intent 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 gives an explicit selection rule against a named sibling: use this instead of describe_file when you only want to see the data, since it is cheaper. There is no explicit 'when not to use' guidance (e.g. when you need types or row counts, use profile_file), but the positive routing is clear.

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