profile_dataset

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

The readOnlyHint=true annotation already covers the safety profile, and the description builds on it rather than repeating it. The description adds genuine behavioral context: it flags data-quality problems (all-null, constant, probable IDs, mixed types, text-stored numbers/dates), discloses sampling behavior ('The result always states whether it was sampled'), and explains the Excel sheet behavior (lists all sheets, warns the first may be a title page). This exceeds what annotations 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?

The description is coherently structured with a purpose statement, a when-to-use paragraph, a reporting summary, and a clearly labeled Args block. It's dense but not bloated. It loses a point for length — the report-per-column enumeration plus the Args block are thorough but arguably verbose; still, nearly every sentence adds value, so it's firmly above average.

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 detail return values, but it still gives a high-level Returns summary (file info, shape, per-column detail, duplicate rows). The tool is genuinely complex (5 params, multiple file formats, quality flags, Excel multi-sheet logic) and the description covers all of it comprehensively. This is effectively a complete specification for a complex 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 documentation coverage is 0%, so the description carries the full burden, and it excels. Every one of the 5 parameters gets a substantive explanation beyond its schema type: path lists supported extensions; sample_rows explains that null reads every row (slower but exact), with the sampling caveat; max_columns explains the response-stays-small tradeoff and that true count is always reported; top_k quantifies behavior; sheet explains the default, the pitfall (title/notes page), and the recovery workflow (call again). This is exemplary parameter 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?

The description opens with a specific verb+resource: 'Summarise the structure and quality of a local data file.' It immediately clarifies scope (local file, not remote) and enumerates exactly what it reports (columns, types, ranges, missing values, quality problems). Though no siblings exist to distinguish from, the description still clearly defines the tool's identity and full responsibility.

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

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

The description gives explicit when-to-use guidance: 'Call this whenever you need to understand a dataset... before analysing it, writing code against it, or answering questions about it.' It also actively advises against an alternative approach: 'Prefer this over reading the file directly... works on files far too large to read, at a small fraction of the tokens.' This is model-level usage guidance that directly shapes agent behavior.

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