Read publication settings

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

Annotations already mark this as readOnly, idempotent, non-destructive, so the description need not restate safety. It adds behavioral value by enumerating the return scope (hero text, logo, theme colours, sections, etc.), which is information not present in the annotations. There is no contradiction between the 'Read' action and the readOnlyHint.

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 description is a single sentence that leads with the key action and resource, then supports it with a field list. 'and everything else on the settings page' acts as a catch-all that avoids an unwieldy exhaustive enumeration. No word is wasted.

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 one optional parameter and no output schema, this description covers the essential information: what it reads, the contents of the result, and its relationship to the full settings page. Combined with annotations for safety/idempotency and schema docs for the parameter, an agent has enough to select and invoke the tool correctly. The only minor gap is an explicit return format, but the field list makes it largely predictable.

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?

The single optional publication parameter is fully described in the input schema, which explains loose hostname matching and defaulting. With 100% schema coverage, the description rightly does not repeat parameter details. Baseline of 3 is appropriate because the description adds no additional parameter context.

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 begins with 'Read the publication's full settings', a specific verb and resource. It lists concrete fields (name, hero text, logo, cover, etc.) and distinguishes itself from the sibling update_publication_settings and the narrower get_sections by emphasizing 'full' and 'everything else on the settings page.'

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 description makes the read context obvious via 'Read' and 'full settings', so an agent can tell it apart from update_publication_settings. It does not explicitly name alternatives or exclusions, but the scope is clear enough that using this for anything but reading full settings would be a mistake. The sibling list strengthens this by contrasting get_sections as a narrower option.

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