Read BrewPage guide

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

Annotations already declare readOnlyHint=true, so safety is covered. The description does add that the payload is short reference documentation with static explanatory content rather than live state, which is useful framing an agent cannot get from annotations. It does not say anything about size, caching, or whether the text is versioned, so it adds context without being rich.

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-loaded with what the tool returns, then two compact topic entries, each sentence carrying distinct content. The second half is dense and slightly run-on (parenthetical lists of sub-steps), but nothing is filler and no sentence merely restates the title or schema.

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 single-enum documentation tool with full schema coverage, no output schema, and read-only annotations, the description supplies the topic scope and one timing hint, which is close to what an agent needs to call it correctly. The remaining gap is that it never routes an agent to the data-manipulation siblings when the real goal is reading or writing page data rather than learning the pattern.

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% and the enum values are already self-describing, so baseline would be 3. The description earns above baseline by unpacking each enum value: 'page-data' is scoped to forms, guestbook, votes, leaderboard and game progress via state.js and the state config, and 'custom-domain' is scoped to profile, DNS records, a check, statuses and fixes. That materially helps an agent pick the right topic.

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?

Opens with a specific framing ('Short reference texts for building on BrewPage') and then names both selectable topics and what each covers, so an agent knows this returns documentation, not page content or page data. It is distinguishable from siblings like get_page_data or get_kv by the fact that the output is reference text about the two named topics. It stops short of explicitly contrasting itself with those siblings.

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 phrase 'meant to be read before writing such a page' gives a real when-to-use cue for the page-data topic, and the custom-domain entry implies use before attempting domain setup. However, only one topic gets an explicit timing hint, and nothing tells the agent when NOT to use this tool or which sibling to reach for instead (e.g., get_page_data for actual stored values vs. this for the how-to).

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