Get Site Content

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate those. It adds value by specifying that the tool returns JSON values for a set of site copy keys, but it does not disclose response shape, ordering, pagination, or any side effects. Given the high annotation coverage, this is acceptable but not particularly 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?

The description is a single, front-loaded sentence that starts with the action verb 'Read' and then specifies the object and examples. Every word contributes to understanding, and there is no filler or redundant restatement of the title. It is well-structured for quick agent comprehension.

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 and zero parameters, the description carries the burden of explaining what the tool returns. It does so by naming the content type ('editable site copy keys') and their format (JSON values) plus concrete examples. However, it stops short of explaining the exact JSON structure or any constraints (e.g., whether all keys are returned in a single response), leaving slight ambiguity for a low-complexity tool.

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 input schema has zero parameters, so the baseline is 4. The description correctly conveys a parameterless operation with phrases like 'all editable site copy keys,' implying no filters are needed. There are no parameter semantics to clarify, and the description adds appropriate context without needing to document inputs.

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 opens with 'Read,' clearly indicating an immutable fetch operation. It specifies the resource as 'all editable site copy keys and their JSON values' and enumerates concrete examples (home stats, announcement banner, featured member, inquiry form URL), which distinguishes it from sibling tools like get_page_content (returns page-specific content) and update_site_content (writes).

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 establishes the tool's role as reading site-wide copy, and the 'all editable' phrasing implies broad access. However, it does not explicitly mention alternatives or provide when-to-use vs. when-not-to-use guidance, unlike tools that state 'To filter by X, use Y instead.' The context implicitly differentiates from update_site_content, but no exclusions are given.

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