Generates an ordered, schema-validated Section array from a brief and structure constraints, returning section types, specs, and rationale—not a full-page HTML document.
Generate an ordered Section array (type, spec, rationale) from a brief and structure constraints. Never return a full-page HTML document.
| Name | Required | Description | Default |
|---|---|---|---|
| brief | Yes | ||
| constraints | No | ||
| coachContext | No | ||
| trendSummary | No |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value by defining the return contract (ordered Section array of type/spec/rationale) and prohibiting full-page HTML output, but says nothing about how ordering is determined, how lockedSectionIds are respected, or whether generation is deterministic.
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 short sentences with the output shape front-loaded and zero filler. Every clause carries information: what is produced, from what inputs, and the one thing never to produce.
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 usefully compensates by defining the returned array shape. However, for a tool with a deeply nested brief/constraints object and 0% parameter documentation, key operational details are absent: what happens with min/maxSections conflicts, how sectionTypes constrains output, and how locked sections interact with ordering.
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 0%, so the description carries the full burden, yet it only names two of the four top-level inputs (brief, constraints) and none of their eight-plus nested sub-fields. coachContext and trendSummary are never mentioned, and it is unclear whether constraints.structure is a hard spec or a hint.
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 (generate) and resource (an ordered Section array with type/spec/rationale), and pins down the input sources (brief, structure constraints). The negative clause 'Never return a full-page HTML document' sharpens the output boundary, though it does not name or contrast with the siblings list_templates / get_recipe.
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?
There is no explicit statement of when to call this versus alternatives, nor any prerequisites (e.g., whether a recipeId from get_recipe should be fetched first). The 'never return full-page HTML' line is an output guardrail, not usage routing, so an agent is left to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.