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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the bar is lower, yet the description still adds real context: the argument-less call returns both lists, topics come back as Markdown, and block source must be read rather than installed. It stops short of saying exactly what the block source location looks like (path vs. URL) or how large the topic payloads are.

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?

Every clause earns its place and the topic mode is front-loaded first, followed by block and no-argument behavior, with a concrete example at the end. The telegraphic, run-on phrasing ("Public: with topic, that topic as Markdown") makes it denser than necessary, but there is no filler.

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?

There is no output schema, and the description carries the return-shape burden well by describing all three outputs. The only gap is that "where to read that reference block's source" is not spelled out concretely enough for the agent to know what it receives.

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 meaning the schema does not: it tells the agent what each parameter yields (topic → Markdown content, block → where to read the source). It does not document format constraints such as acceptable slug casing or what happens when both are supplied.

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 precise verb (read) and resource (a Storefront Kit topic or reference block) and enumerates all three operating modes: topic returns Markdown, block returns the source location, and no arguments returns the topic and block lists. An agent can distinguish this from kit_learn (which supplies the lists) without opening either schema.

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 explicit when-to-use routing: read assemble-a-shop, world-class-ordering-ux, verify-contract and the-return-page before building, and the others only when the steps name them. It also adds a when-not constraint for blocks ("read it, never install it") and an efficiency rule ("Read each topic once"), leaving nothing to inference.

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