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

Annotations already declare it is not read-only and not destructive, and the description adds real value: the query is persisted the moment this runs, dashboard attachment requires edit permission, and the call surfaces an approval card to the user. It does not warn that the call is non-idempotent and could create duplicate charts if retried, which is the main missing behavioral note.

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 core action and the critical prerequisite are front-loaded, and every sentence carries instructions. The final skill-loading sentence is a bit of an appendix, but it is actionable rather than 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 create tool with a deeply nested spec and no output schema, the description never says what comes back — notably the created chart/query id an agent would need to update or attach it later. Permissions, prerequisites, and approval behavior are covered well, so the gap is narrow but real.

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 coverage is 100%, so all seven parameters are already documented, including reason, dashboardId append behavior, and description. The description mostly restates that spec must match the run_funnel_query spec, adding only marginal meaning over 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 and resource ('Save a new funnel query as a chart') plus the optional side effect of dashboard attachment. It also implicitly distinguishes itself from run_funnel_query, which executes rather than persists, and from update_funnel_query, which modifies an existing chart.

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?

Explicitly prescribes the prerequisite ('run it first so you know it works'), names the exact spec source (run_funnel_query), states the extra permission needed for dashboard attachment, and directs the agent to load the manage-dashboards and funnel-queries skills before calling. This is near-complete when/when-not guidance.

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