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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "this tool changes nothing" and enumerates the exact actions that are rejected rather than silently ignored. It goes further by noting the `performance` window is a bounded lookback and that the per-step funnel exposes reason codes, but it omits any note on the cost or latency of the AI/data-heavy `get` path. The only weakness is that much of the text details write semantics the tool cannot perform, which is boundary-setting rather than behavioral detail the agent needs here.

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-loading is excellent — the read-only scope and the three valid actions appear in the first sentence. However, the bulk of the middle section is an itemized tour of create/update/trigger/test/delete parameters that this tool will refuse, which is dead weight for a three-action read surface and dilutes the signal the agent needs.

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 read-only tool with no output schema, the description covers enough: it says `list` is a paginated index with search and folder filtering, `get` returns the full triggers/actions JSON, and `performance` returns a step funnel with reason codes. What's missing is anything about result size or default paging behavior on `get` for large scenarios, which matters given the nested trigger/action tree.

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 the per-parameter meaning is already fully documented and 3 is the baseline. The description does add interpretive value for `performance` (per-step funnel, which step is breaking, defaults implied by the schema) and clarifies that `get` returns full triggers/actions JSON plus generation data, but it spends most of its parameter prose on create/update parameters this read-only tool refuses.

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 first sentence delivers a specific verb+resource plus scope: "Read scenarios — this tool changes nothing. Actions: list, get, performance." It then explicitly separates the tool from its nearest sibling by declaring that all write actions live on `scenarios_manage` and are refused here, so an agent can pick correctly without opening any schema.

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?

Routing is explicit and multi-layered: it names the sibling for writes, tells the agent to call `get_action_types`/`get_trigger_types` before building, points to `executions` for reading the failing runs behind a performance dip, and even flags when to prefer `medias`' `attach_comment_to_dm` over authoring a scenario. When-not-to-use is covered by the "refused here" boundary and the narrow-post exclusion.

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