apply_report_operations

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

The description discloses behavior beyond the annotations (destructiveHint=true) by detailing atomic application, validation before HTTP calls, ETag optimistic-concurrency with retry, write-once placement/dataRoles, auto-naming and auto-sizing, and the save-as behavior to avoid destructive edits. It also explicitly states 'the whole batch is applied atomically (all succeed or nothing changes).' This is far more than annotations provide and is transparent about mutations.

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?

Despite its length, the description is well-structured with clear sections: an opening shorthand of usage, operation keys, layout & titles specifics, validation and concurrency behavior. Every sentence carries purpose—no fluff. It is front-loaded with the core verb and resource, and the technical details are organized logically for an agent to parse quickly.

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 complexity of this tool (multiple operation types, layout rules, validation logic), the description is exceptionally complete. It covers operational invocation, validation guarantees, concurrency handling, and the output options (dry_run, result_report_name for save-as, response_format). It also references output verification via export_report and provides a comprehensive example. The presence of the output schema further reduces the need for result-format discussion, but the description still addresses all needed context.

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 description coverage is 100% and the schema is rich, but the description adds even more semantic depth: it explains the operations array structure with an example, clarifies layout and placement options with concrete JSON snippets, and describes constraints like 'relativeToObject' against existing objects and the write-once rule. This exceeds the schema's role descriptions and gives crucial contextual meaning.

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 (apply operations to a report) and accurately characterizes the tool as the 'authoring workhorse' for adding pages, objects, parameters, and swapping data sources. It distinguishes itself from sibling tools like create_report, describe_report_objects, and get_report_outline by clearly scoping its role in the batch modification workflow.

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 says 'This is how you add pages, add objects... set parameters, and swap data sources,' and gives detailed operational patterns. It provides when-to-use and when-not-to-use (e.g., page/report headers accept ONLY control objects, same-batch forward references fail). It names complementary tools (describe_report_objects, get_castable_columns, get_report_outline, export_report) and explains their roles for contextual layering.

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