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

Beyond the annotations, it explains paging defaults, omitted settings semantics, custom CSS chunking, revision consistency, theme_has_native_defaults behavior, device override precedence, all_pages scope, page/post independence, and the Advanced plan requirement. These are substantial behavioral details for a read-only tool.

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 purpose is front-loaded, and the dense details are largely relevant to correct invocation. It is a long paragraph, but most sentences earn their place by preventing pagination, revision, or custom CSS mistakes.

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 six-parameter read tool with no output schema, the description is complete enough: it explains returned settings semantics, pagination, custom CSS handling, revision use, device precedence, all_pages behavior, and plan requirements. An agent should be able to call it correctly without additional context.

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 the baseline is 3, but the description adds useful meaning: query helps discover areas/labels/keys, offset must reuse filters and revision, and section=custom_css changes paging behavior and must be read chunk-by-chunk before replacement. It does not fully document every parameter nuance 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?

The description states a specific verb and resource: read Design Studio settings, supported rules, draft/published values, and exact revision. It is clearly a read-only paged design-settings tool, distinguishable from mutation siblings like update_design and publish_design.

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?

It gives clear operational guidance: use query to discover controls, follow next_offset with the same filters and revision for more, and request section=custom_css before replacing CSS. It lacks explicit when-not-to-use guidance or named alternatives such as get_blog_settings.

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