HTML Email Playbook

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered without the description. The description adds genuine behavioral value beyond that: it discloses the shape of the returned payload and, notably, that slots are 'placeholders the model should fill', which tells the agent the result is a template to be completed rather than finished output.

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 with the payload contents front-loaded and the invocation guidance second. The return-field enumeration is long but each item is informative given there is no output schema; nothing reads as filler, though the single sentence does run dense.

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 carries the burden of describing return values and does so comprehensively, plus it supplies the prerequisite call sequence. An agent has everything needed to select and invoke this read-only, one-parameter tool correctly.

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 100%: the single 'name' parameter is documented and constrained by a six-value enum, and the schema itself already instructs 'Get the list from list_components first.' The description adds no naming conventions, aliases, or format guidance beyond what the schema provides, so the baseline of 3 applies.

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?

States a specific verb ('Return the full record') and resource ('a single component') and enumerates exactly what the record contains: title, description, narrative body, HTML pattern, slots, VML/responsive flags, code examples. This is clearly distinguishable from the sibling list_components, which returns a collection rather than one full record.

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?

Explicitly sequences the call ('Use after list_components') and gives the motivating condition for calling it ('to fetch the actual HTML pattern to paste into an email'). It routes the agent correctly relative to its main sibling, though it states no when-not conditions and does not mention the other siblings (get_rule, get_playbook_rules, list_categories).

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?

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower. The description adds genuinely useful behavioral context beyond them: an approximate payload size (~16 KB) for the category-less checklist call and the explicit statement that components are out of scope. It stops short of saying what the full body/code payload costs, but the coverage is good.

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 the core purpose, then format semantics, then the sibling hand-off — a sensible order with no filler sentences. It is dense and slightly run-on, blending format and category rules into one clause chain, which costs a point.

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 compensates by naming the returned fields for each format (slug, title, description, rules list for checklist; plus markdown body and HTML/CSS for full). What an agent needs to call and interpret the result is present; pagination or rate-limit behavior is not addressed but is not obviously required for a ~16 KB read.

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 100% and both enums are documented there, including the full-vs-checklist defaults and the category dependency, so the description largely restates structured data. Its only added value is the ~16 KB size signal for the omnibus checklist call. 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?

States a specific verb+resource ("Return rule pages") and immediately distinguishes the two operating modes by name. It also carves out what the tool does NOT return (components) and names the sibling tools that cover that case, so an agent can separate it from get_rule and list_components without opening a 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?

Explicit routing: "Start with the checklists, then fetch the pages you need with get_rule" tells the agent the intended workflow and the follow-up tool. The exclusion note ("Components are not included: use list_components / get_component") removes the main wrong-tool risk.

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), so the bar is lower. The description still adds real behavior: the accepted slug input forms and the fact that include_examples returns code already present in the body, which prevents redundant fetches. No contradiction with annotations.

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 sentences, front-loaded with the return payload, then input flexibility, then slug sourcing, then the sibling comparison. Every sentence carries information; slight density but 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?

With no output schema, the description compensates by enumerating the returned fields and flagging that the body contains the page's HTML/CSS code. Combined with annotations and full schema coverage, an agent has everything needed to call it correctly.

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 baseline is 3, but the description genuinely extends the schema: it documents a third accepted slug format (a page link like '/email-playbook/compatibility/responsive/') that the schema description omits, and clarifies that include_examples is additive rather than a filter.

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?

States a specific verb and resource ('Return one rule page') and enumerates exactly what comes back: slug, category, title, description, checklist, and markdown body. It also distinguishes itself from get_playbook_rules by noting it is 'much smaller than fetching the whole category', so an agent can separate the two without opening schemas.

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?

Gives a clear entry point ('Get the slugs from list_categories') and names the alternative (get_playbook_rules) with the condition that favors this tool (single rule vs. whole category). It stops short of explicit when-not-to-use guidance, but the routing context is unambiguous.

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?

Annotations already declare readOnlyHint, openWorldHint=false, and idempotentHint, so the safety profile is clear. The description adds behavioral context about what data is returned (category descriptions, page counts, page slugs/titles) and distinguishes the dimension from components. It does not explicitly state that it takes no parameters or that results are static, but the schema covers the parameter side.

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 compact and front-loaded: it states the return shape first, then enumerates categories, then gives cross-tool guidance. The category enumeration is slightly dense but informative; every sentence contributes to selection or invocation.

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 zero-param, read-only listing tool with no output schema, the description is complete enough to call correctly: it says what is returned, when to use siblings, and how categories are structured. The lack of an explicit statement that no parameters are accepted is a minor gap covered by the schema.

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?

With zero parameters and 100% schema coverage, the baseline is 4. The description correctly implies no inputs are needed and spends its words on output content instead.

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 specific verb (List) and resource (rule categories in the Email Playbook) and explains exactly what each entry contains (one-line description, page count, slug/title). It also enumerates the four categories, making the tool's scope 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?

It explicitly routes the agent: 'Pass a page slug to get_rule to fetch just that page' and 'For reusable components, use list_components instead — they live in a separate dimension and are not returned by get_playbook_rules.' This names alternatives and their conditions.

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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is covered; the description adds the otherwise-absent return shape ("all" components plus the specific metadata fields), which matters because there is no output schema. It does not address ordering, exhaustiveness, or whether results can be empty, so it is strong but not exhaustive.

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, front-loaded with the purpose and return contents, then the routing instruction. The metadata enumeration is functional rather than filler because no output schema exists to carry it, and no sentence is redundant.

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 zero-parameter read-only discovery tool with annotations covering safety, the description supplies the purpose, the result fields, and the workflow position, which is close to complete. The only gap is the relationship to the overlapping list_categories sibling, which also concerns component categorization.

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 takes zero parameters, so there is nothing for the description to disambiguate; per the rubric this lands at the baseline of 4. The schema is trivially complete (empty object, additionalProperties false).

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?

States a specific verb (list) and resource (all reusable email components in the playbook) and enumerates exactly what metadata each entry carries (name, subcategory values, description, Outlook VML requirement, responsive flag). It explicitly positions itself against the sibling get_component, so an agent can tell the discovery tool from the fetch tool 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?

Gives clear sequencing guidance: "Use this first to discover what components exist before calling get_component," which is an explicit when-to-use plus the alternative tool. It does not distinguish itself from the other read-only siblings (list_categories, get_playbook_rules) or state any when-not conditions, so it falls short of a full 5.

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