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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavioral facts: unpublished pages are included, and results carry their link plus the exact rules for linking to them. It does not mention result limits or ordering, keeping it short of a 5.

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?

Two tight sentences, front-loaded with what the tool returns, then default behavior and filtering options. No filler or restatement of the tool name.

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?

With no output schema, the description usefully says what each entry contains (link and linking rules), and the filtering semantics are covered. Missing are pagination/result-size behavior and any hint about how it differs from studio_list_pages, which for a list tool is a minor but real gap.

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 only 33% (just session_id documented), so the description must carry the rest — and it does: 'kind' is mapped to the three enumerated values and 'name' is clarified as a partial match ('part of a name'), not an exact one. The required session_id is left to the schema, which documents it adequately.

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 concrete verb and resource ('list ... the pages of the app') and enumerates the kinds covered (sections, widgets, web plugins), plus what is returned (link and linking rules). The one weakness is that it never distinguishes itself from the sibling studio_list_pages, which by name sounds like the same resource, leaving an ambiguity an agent must resolve on its own.

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 sentence 'Without arguments, every page; narrow the list with kind, or with part of a name' explains default and narrowing behavior, which is useful. But it gives no when-to-use/when-not guidance and never mentions the competing studio_list_pages tool, so tool selection is only implied.

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