iva_whiteboard

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

With no annotations provided, the description carries the full behavioral burden. It conveys a state-mutating, potentially destructive profile through verbs like add/delete/clear/copy, stop-demo, and undo, which is genuinely useful for an agent deciding whether invocation is safe. However, it does not disclose side effects such as demonstration actions being shown to participants, the irreversible nature of deletes, or any confirmation gating — those details appear only in the action enum and the confirm parameter description, not in the main description.

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 dense sentence enumerates all 21 operations with virtually no fluff, and the domain ('IVA whiteboard') is front-loaded before the operation list. The 'Clients API v2.28.12' suffix is a minor oddity but supplies version context in one short phrase. It is appropriately sized for a multi-action dispatcher tool where a verbose explanation would hurt usability.

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?

This is a high-complexity tool: 21 actions, 17 parameters with nested objects, no output schema, and no annotations. The description covers the action space at summary level but does not address return values (despite the absent output schema) or side effects, and does not map which parameters apply to which actions. The schema's action enum descriptions compensate substantially, but the overall definition leans heavily on the schema rather than the description.

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% — every one of the 17 parameters is documented — so the baseline is 3 and the description need not compensate. The description names parameter families (cursor, demo state, books, pages) but adds no semantic detail beyond the schema. The action parameter's enum descriptions carry the real per-action parameter meaning, and the tool description does not extend or clarify it.

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 uses specific verb+resource pairs: 'start/stop demonstration', 'manage books and pages (add/delete/update/clear/copy/reorder)', 'export to PNG', 'undo', 'save change', and 'update cursor/demo state'. It clearly distinguishes iva_whiteboard from all 28 sibling tools, none of which cover whiteboard functionality. The final version stamp 'Clients API v2.28.12' adds useful provenance context and makes the tool's scope immediately evident.

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?

Usage context is implied through the enumerated operation families — demonstration control, book/page management, export, undo/save — and the sibling set makes it evident this is the only whiteboard entry point. However, there is no explicit when-to-use guidance, no exclusions, and no statement about when a sibling tool would be the better choice. The per-action usage requirements (e.g., 'start_demo Requires whiteboardState: {pageId, left, top, right, bottom}') live in the action enum descriptions inside the schema, not in the tool description itself.

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