HTML Email Playbook

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

No annotations are provided, so the description carries the full burden. It enumerates the returned fields comprehensively, including slots and flags, and implies a read-only operation (returning a record). While it does not mention auth requirements or error cases, the description sufficiently discloses the tool's behavior and output for a retrieval tool.

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 two sentences, front-loading the return value list and then usage instruction. No redundant information; every phrase contributes to understanding the tool's function and workflow.

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 explains what the tool returns by listing fields. It covers the essential aspects for a single-record retrieval tool: what it does, what it returns, and when to use it. It lacks explicit mention of output format or error handling, but for a simple read tool, this is adequate.

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% with a single parameter 'name' that has enum values and a description. The description adds 'Use after list_components', reinforcing the parameter's context but not adding new semantic meaning. Baseline is 3 due to high schema coverage, and the description provides only marginal extra guidance.

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 clearly states the verb 'return' and the resource 'single component', and lists specific fields it returns (title, description, narrative body, HTML pattern, slots, flags, code examples). It distinguishes from sibling tools by mentioning 'use after list_components', indicating it retrieves details for one component while list_components returns a list.

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 explicitly says 'Use after list_components to fetch the actual HTML pattern to paste into an email.' This clearly indicates when to use this tool (after listing) and its purpose (to get the HTML pattern). It does not explicitly state when not to use it, but the context is sufficient for an agent to understand the workflow.

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

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

Since no annotations are provided, the description carries full burden. It transparently describes the return content (title, description, markdown, code examples) without contradictions. No side effects are hinted, which is appropriate for a read-only tool.

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?

Two sentences that efficiently convey purpose, return content, and usage context. No redundant information, and the purpose is front-loaded.

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 simple tool with one parameter and no output schema, the description adequately covers what the tool returns and when to use it. No gaps are evident.

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% with clear enum values and description. The description adds no extra parameter detail beyond 'a given category', but the schema already fully explains the parameter, so baseline 3 is appropriate.

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 clearly states the tool returns full rule pages for a given category, specifies what each rule includes (title, description, markdown, code examples), and distinguishes from siblings like get_component which returns component details.

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 explicitly advises using this tool to teach a model patterns for a specific concern, providing clear context. It does not mention when not to use it or alternative tools, but the usage guidance is strong.

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

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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explains that the tool returns categories with a description and page count and explicitly states that components are not included. No side effects or hidden behaviors are relevant for this parameterless read operation.

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 concise with three sentences: the first defines the action and output, the second lists categories, and the third provides sibling guidance. No unnecessary words, and key information is front-loaded.

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?

Given zero parameters, no output schema, and no annotations, the description is fully complete. It explains the tool's purpose, output content, and integrates sibling context, leaving no gaps for an agent to misunderstand.

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?

There are no parameters, so the schema coverage is 100%. The description adds value by detailing what the tool returns and listing examples of categories, which enriches understanding beyond the empty schema.

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 clearly states the tool lists all rule categories with a one-line description and page count. It enumerates the categories explicitly and distinguishes itself from the sibling tool list_components, making the purpose unambiguous.

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 provides explicit guidance on when to use this tool (to list rule categories) and when not to (for reusable components, use list_components instead). This direct alternative reference makes usage very clear.

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

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

No annotations are provided, so the description bears full burden. It accurately describes what the tool returns (list of components with metadata), but could add details like result ordering or data freshness. Given the simplicity of the tool, the description is sufficient.

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, clear sentence that efficiently conveys purpose, output, and usage guidance without unnecessary words.

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?

Given no parameters and no output schema, the description fully covers the tool's purpose, usage context, and output details, leaving no gaps for a simple list 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 tool has zero parameters, and schema coverage is 100%. The description adds value by enumerating the metadata fields returned, going beyond the schema.

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 clearly states the action (List), the resource (reusable email components), and specifies the returned metadata fields. It also distinguishes from the sibling tool get_component by positioning list_components as a discovery step.

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 explicitly advises using this tool first to discover components before calling get_component, providing clear guidance on when to use it relative to a sibling.

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