state_read

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered. The description adds non-obvious behavior beyond that: the data is a cache (implying possible staleness relative to live server state), large sections are paged, and results come back as JSON text rather than structured objects. It omits refresh/invalidation semantics for the cache, which keeps it from 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?

Three short sentences, each doing distinct work: scope, the omit-section shortcut, and the paging/return format. The section list and the overview hint are front-loaded where an agent will read them first.

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 handles the return side by naming the JSON-text paged format and the compact-overview mode, which is the essential thing an agent needs. For a 4-param, mostly-optional read tool this is nearly complete; only cache freshness behavior against live state is unaddressed.

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 only 25%, so the description must carry weight, and it does: it enumerates valid 'section' values and explains that omitting it yields a compact overview, and it links the paging sentence to offset/max_characters. It never states that offset/max_characters are the paging controls by name or their units/limits, leaving a small gap.

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?

Specific verb+resource: 'Read a cached authoritative state section', with a concrete enumeration of the section keys (table, zones, snaps, drawings, decals, players, groups, timemachine, policy, lighting, music). An agent knows exactly what this returns. It does not explicitly contrast with nearby read siblings such as object_read or objects_list, so it stops short of 5.

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 one piece of genuine routing guidance — 'Omit section for a compact overview' — which is a usable when-to-do-what rule. But there is no statement of when to prefer this over object_read/objects_list/events_read, nor any prerequisites or exclusions. Usage is implied rather than prescribed.

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