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

Annotations only declare readOnlyHint=false, so the description carries some burden. It usefully discloses that saved_template_id values are replaced, that views are free (no watermark/unlock), and that it returns artifact_id. However it omits what 'live data' implies operationally, whether saved views can later be updated/deleted, and any auth or quota context.

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-loads the core action and definition, then compactly covers the key param behavior and return value in two sentences. Every clause earns its place without filler.

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?

For a mutation tool with 5 optional params, no output schema, and a nested 'state' object, the description is strong: it defines the artifact, return value, and saved_template_id override behavior. It could better distinguish from update_view/save_as_template and mention validation of spec_version, but it's close to complete.

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%, so baseline is 3. Description adds marginal value by clarifying saved_template_id semantics ('anything you pass replaces its value') but does not explain source syntax, spec_version format, or state keyed-by-name beyond the schema.

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 ('Save a view') and elaborates what a view is with concrete examples (dashboard, Markdown document, feed of posts). Clearly distinguishes from siblings like update_view (mutation of existing view) and generate_markdown through the 'view language renders with live data' framing.

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?

Implies usage via 'a view the user wants to keep' but never explicitly states when to use this versus save_as_template, update_view, or generate_markdown. The saved_template_id sentence gives some context ('starts from a view template saved earlier') but no clear when/when-not guidance or alternative routing.

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