Workbooks List Report Columns

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the description earns credit for the extra detail it does provide: it auto-paginates to the last page and returns an aggregated result with nextPageToken null. That is genuinely useful behavioral context an agent cannot get from the annotations or 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?

Two short sentences, no filler, with the pagination behavior front-loaded after the purpose statement. Minor deduction for the awkward mid-sentence line break and a slightly garbled clause about returning 'the keys of Sigma's page'.

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 spelled out, and the one thing an agent could not otherwise predict — that all pages are fetched and merged — is explained. Only the report_id semantics are left thin, which is a small gap given the tool's low complexity.

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?

Only one parameter (report_id) exists and schema description coverage is 0%, so the schema gives nothing but 'string'. The description implies the identifier is a report but adds no format, source, or validity guidance; for a single self-evident parameter this is tolerable but below what full compensation would look like.

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 columns') plus scope ('of every element in a report'), so the agent knows this is a report-wide column enumeration rather than a single-element lookup. It does not name the nearby alternatives (workbooks_list_report_elements, elements_get_element_columns), so the differentiation is inferred rather than stated.

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 'of every element in a report' implicitly signals when this tool is preferred over a per-element column fetch, but the description never says so explicitly, nor does it state prerequisites (e.g., needing a valid report_id from workbooks_list_reports). Usage is inferable but not guided.

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