Two Minute Toolkit

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

Annotations only cover the read-only/idempotent profile, and the description goes well beyond: hard limits (3–8 stages, 1–3 word names, ~12 word details), the degradation behavior implied by those limits, the instruction to infer missing details rather than ask, and the post-call obligation to always surface the image link because inline images are not saveable. That is exactly the operational context an agent cannot get from structured fields.

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 visual spec and then routing, limits and the image-link rule in a logical order. It is dense at roughly 150 words with several long clauses, but nearly every sentence carries distinct information; only the image-link sentence sits oddly inside a tool description.

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 7-parameter generative tool with no output schema, the description supplies the missing return-value information (an image link plus an Edit link into the builder), the visual contract, and the constraints. Nothing an agent needs to call it correctly or to report results back is absent.

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%, so every parameter including style, center, palette and stage detail already carries rich documentation. The description restates the ordering semantics and length guidance that the schema already spells out, adding little new parameter-level meaning beyond the constraints summary.

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 ("Generate a slide-deck-quality cycle diagram") and immediately specifies the geometry: 3–8 stages, 12 o'clock start, clockwise, closing arrow. The two style variants ("nodes" vs "segments") are named, so an agent can distinguish this from create_process, create_timeline and create_hub_spoke without opening any 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 when-to-use clause ("Choose it when the process repeats") with concrete examples: PDCA loops, flywheels, lifecycles, feedback loops. It also names the three sibling alternatives and the condition that selects each (process for one-way steps, timeline when dates matter, hub and spoke for unordered items around a centre).

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 only declare readOnly/idempotent/closed-world, and the description adds substantial behavior beyond that: node types are inferred, EVs roll back automatically and best options are accent-coloured while rejected ones get a prune mark, probabilities not summing to 100% are warned about but still drawn, and overflow is dropped 'deepest levels and last-listed nodes first' with a warning. Hard limits (5 levels, 5 branches, 40 nodes) and the instruction to always return the image link are disclosed too.

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?

It is long but front-loaded: what it draws, then how EV/inference works, then when to choose it, then limits and the link requirement. A few clauses duplicate the input schema's own property descriptions (payoff column, probability warning), which costs it a point, but no sentence is purely 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?

For a rich 8-parameter generative tool with no output schema, the description covers everything an agent needs: how types are inferred so it can omit them, how EV is triggered, the hard structural limits, what happens on invalid probabilities, and the requirement to hand the user the image link. Nothing material is missing.

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%, so the schema already explains payoff, probability, label, prefix/suffix, showEV and palette in detail. The description restates the payoff/prefix/suffix convention and the 'Strong demand · 60%' rendering, adding little beyond the schema; the genuinely additive guidance ('infer missing details rather than asking') is workflow, not parameter semantics. Baseline 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?

The opening sentence names a specific verb and artifact ('Generate a slide-deck-quality decision tree') and pins down the exact visual convention (square/circle/triangle, left-to-right columns). The second half explicitly separates the two supported use cases — decision analysis under uncertainty and plain yes/no flowcharts — so an agent knows precisely what this produces.

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 a positive routing rule ('Choose it for choosing between options under uncertainty... expected-value homework, yes/no flowcharts') and three named exclusions with the sibling that handles each: issue tree for decomposition, chevron process for ordered steps, Harvey ball matrix for criteria scoring. This maps directly onto create_issue_tree, create_process and create_harvey_matrix.

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 mark this read-only/idempotent/closed-world, and the description adds substantial non-obvious behavior: one system renders but is warned, more than 12 are dropped, self-sizing between 880–1280px, 2x PNG rendering, the Edit link, and the critical 'ALWAYS give the user the image link' because inline images can't be saved. It also carries a privacy constraint (first names/roles only, no identifying client details) that nothing else conveys.

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 purpose, then usage routing, then limits, then the link/rendering caveat—a sensible order. It is long and dense for a single paragraph, with the limits list partly duplicating the schema, but nearly every clause carries operational value.

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?

No output schema exists, so the description must describe the artifact, and it does fully—layout, line semantics, legend, sizing, PNG behavior and how to deliver the result. Combined with the rich nested schema, an agent has everything needed to call it correctly and present the output.

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%, so every parameter and nested field is already documented with examples, enums, defaults and limits; the description mostly restates those limits (2–12 systems, 0–8 members, 1–3 word names, ~10-word details) in summary form. It adds little semantic information beyond the schema, so the baseline 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 and resource ('Generate a clean ecomap, Hartman style') and spells out the visual structure it produces—centre circle, 2–12 surrounding systems, line styles, arrowheads, legend. It also explicitly names the sibling tools it is not (hub and spoke, mind map, org chart), so the agent can distinguish it 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?

'Choose it to map a person's or family's relationships with outside systems; use a hub and spoke for neutral parts..., a mind map when items branch further, and an org chart for reporting lines' gives explicit selection criteria and named alternatives. It further adds the operating instruction to infer missing details rather than asking, which is actionable guidance an agent needs.

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 only say readOnly/idempotent/closed-world; the description adds substantial context beyond that: it instructs the agent to infer 4–6 categories and 2–4 causes instead of interrogating the user, notes overflow behaviour (more than 8 categories dropped with a warning), discloses the builder Edit link, and — importantly — instructs the agent to always surface the image link because inline chat images cannot be saved. That last point is critical delivery behaviour found nowhere in structured fields.

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?

Purpose is front-loaded and the alternative-routing sentence is dense but efficient. It loses a point for a long run-on middle section and for repeating limits (1–8 categories, 6 causes, 3 sub-causes) that the schema already states verbatim.

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?

No output schema exists, and the description fills that gap by explaining what the deliverable is and how to hand it to the user (the link renders the exact chart and can be pasted into a slide or Markdown). Combined with inference defaults, overflow behaviour and branding control, an agent has everything needed to call this correctly and deliver the result.

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%, so the schema already documents presets, palettes, limits and string shorthands; the description largely restates those same limits (1–8 categories, 6 causes of 2–7 words, 3 sub-causes). Its only genuine addition is the population strategy — infer 4–6 categories and 2–4 causes rather than asking — which is modest value on top of an already complete schema. 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 and artifact ('Generate a slide-deck-quality fishbone diagram (Ishikawa or cause-and-effect)') and then describes the concrete layout: head box, horizontal spine, 1–8 alternating category bones, causes and sub-causes. It explicitly contrasts itself with create_lab_fishbone, issue tree, mind map and SIPOC, so an agent can distinguish it from every near neighbour.

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?

Names the exact domains where it applies (quality, Lean/Six Sigma DMAIC Analyze, healthcare QI, incident reviews, 'why does this keep happening' slides) and pairs each alternative with the condition that selects it — issue tree for MECE/KPI breakdown, mind map for open brainstorm, SIPOC for process scoping, create_lab_fishbone for BMP/CBC skeletons. Both when-to-use and when-not-to-use are covered.

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 read-only, idempotent and closed-world, and the description adds operational traits beyond them: infer ratings and bullets rather than asking, an empty object is valid input, the user can adjust via an Edit link, and inline chat images usually cannot be saved so the image link must always be given. That last point is genuinely non-obvious and valuable, though return-value framing stays thin given there is no output schema.

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 resource and layout, then routing, then limits, then the image-link rule — a sensible order. It is long for a single description and repeats the bullet and conclusion limits that also appear in the text just above and in the schema, but no sentence is truly wasted.

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?

Covers an 11-parameter nested-object tool completely: layout, all five required forces, inference policy, evidence-length limits, the conclusion line, and how to deliver the result to the user. With no output schema, the instruction to always return the image link fills the one gap that would otherwise cause a silent failure.

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%, so the schema already documents every field, including rating enums, bullet caps and the 640–2400 width range. The description restates a few of those (5 bullets of 4–10 words, one-sentence conclusion, ratings vocabulary) but adds almost no field meaning the schema does not already carry, which is the baseline-3 case.

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 (generate a Porter's five forces diagram) and describes the exact layout: rivalry centre, entrants above, substitutes below, suppliers left, buyers right, arrows inward. This is concrete enough that an agent can distinguish it from create_swot or create_quadrant_matrix without opening the 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?

Explicitly says when to choose it (industry attractiveness or competitive pressure for strategy, market-entry, investment or case-interview slides) and names three sibling alternatives with the conditions that select them: Harvey matrix for scoring options, hub and spoke for unordered items, mind map for open-ended brainstorming.

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 safety (readOnly, idempotent, closed-world), and the description adds genuinely non-obvious behavior: row/marker limits, automatic low/high swap with a warning, axis clipping of out-of-range bars, permission to infer missing details rather than ask, and the builder Edit link. The critical delivery rule — that inline images usually cannot be saved so the link must always be given — is behavioral context an agent would otherwise miss. Slightly short of 5 because it doesn't say what the response object actually looks like beyond the link.

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 purpose and content, then selection rules, then limits, then delivery instructions in a logical order. It is a dense single block — long for one paragraph — but nearly every sentence adds distinct operational value; only the repeated marker/row limit restates what the schema already declares.

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?

Thirteen parameters with nested objects and no output schema, and the description still covers what matters: hard limits, warning behaviors, defaults, the infer-don't-ask policy, post-generation editing, and the mandatory link delivery. An agent could call this correctly on the first attempt from the description alone.

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% and is exceptionally rich (units, swap behavior, palette first-color rule, decimals default), so the schema carries the parameter burden. The description adds only the display-formatting guidance (plain numbers, prefix/suffix/decimals) and the assumption-line example, which the schema already documents.

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 artifact ("Generate a slide-deck-quality football field chart") and then spells out exactly what that artifact contains: one floating bar per method, shared axis, labels at bar ends, markers, shaded range. Explicitly distinguishes itself from the timeline, Harvey ball matrix, and pyramid siblings.

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 both a positive selection rule ("Choose it for valuation ranges… and for any comparison of low–high ranges on one scale, such as salary bands, cost ranges") and named alternatives with the condition that selects them (Gantt for dates, Harvey matrix for scores, pyramid/funnel for stage volumes). Nothing is left to inference.

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?

Beyond the readOnly/idempotent annotations, it discloses hard limits (2–12 rows, 1–8 criteria, 40-char names), out-of-range handling (scores clamped, null leaves blank), and the conditional Notes column. It also explains the delivery behavior: the image link must always be given because inline images can't be saved, and an Edit link lets the user adjust.

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 purpose, followed by routing, limits, and output instructions; every sentence carries some action-relevant content. It's dense for a single paragraph, and the limits clause partially duplicates schema constraints, but nothing is 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?

For a 9-parameter generative tool with no output schema, it covers structure, defaults-by-omission, edge cases (clamping, blank cells), and what the caller must return to the user. Nothing an agent needs to invoke it correctly is missing.

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 most parameter meaning is already structured; the description's limits restate schema min/max values. It does add cross-field semantics — score ranges tied to the chosen style, clamping, and blank cells from null — which helps an agent populate rows[] correctly rather than reading each property doc.

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?

Opens with a specific verb+artifact ("Generate a slide-deck-quality Harvey ball matrix") and immediately defines the row/column structure and cell styles. It explicitly names the sibling types it is not (timeline, process, pyramid/funnel, hub and spoke, mind map, org chart), so an agent can route correctly without opening other 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 positive selection rule ("compare vendors, tools, plans or features side by side") plus explicit when-to-use-an-alternative rules mapped to each competing sibling. It also advises inferring missing details rather than asking, which removes a common agent stall.

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 only declare readOnly/idempotent/no-open-world, so the description must carry the operational burden and does: it says to infer missing details rather than ask the user, states hard limits (3–10 spokes, one level, 1–3 word names, ~12 word details), and explains the builder Edit link for post-hoc adjustment. Most importantly it gives the output-handling rule — always surface the image link because inline chat images usually cannot be saved — which no annotation or schema conveys.

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 what the diagram is and when to choose it, then limits, then output handling — a sensible priority order. It is dense and nearly every clause carries information, though the list of alternative diagram types and the example-domain list (platform/products, team/stakeholders, etc.) are somewhat expansive for a single tool description.

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 still tells the agent what the artifact is and how to deliver it (image link, editable in builder). Combined with a fully documented 8-parameter schema, an agent has everything needed to call this correctly and hand the result to the user.

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; the description still adds value by stating the authoring constraints the schema can't express — 3–10 spokes, single level, 1–3 word names, roughly 12-word details. It does not add per-parameter meaning beyond that (e.g. when to set palette vs hubColor), so it sits above baseline but not at the top.

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?

Opens with a specific verb and resource ("Generate a slide-deck-quality hub and spoke diagram") and immediately describes the visual anatomy: a central hub circle, 3–10 coloured satellite cards, spokes, optional details and arrowheads. This is unmistakably distinct from create_cycle, create_process or create_fishbone based on the description alone.

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 an explicit selection rule ("Choose it when several items relate to one centre with no order between them") plus four concrete example scenarios. It then routes the agent away to named alternatives with their own conditions: cycle for repeating sequences, process for one-way steps, mind map for branching, org chart for reporting lines.

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 safety (readOnlyHint, idempotentHint), but the description adds substantial non-obvious behavior: hard limits (4 levels, 6 children, 40 boxes) with the truncation rule ('extras are dropped with a warning, deepest levels and last-listed boxes first'), the instruction to infer missing details rather than ask, the builder Edit link, and the crucial caveat that inline chat images can't be saved so the link must always be given.

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 purpose and the 'choose it for / use X instead' routing are front-loaded, and the trailing operational guidance about limits, inference and the image link earns its place. It is a single dense paragraph though, and the layout description in the first sentence runs long relative to the decision-relevant content.

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 complex, deeply nested chart-generation tool with no output schema, the description supplies everything an agent needs: structural limits, the semantic choice between issue tree and value driver tree, nesting/colour/operator conventions, and explicit post-call instructions for surfacing the returned image link. Sibling differences are also resolved in-text.

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%, so every parameter including the nested node fields is already documented in structured data. The description reinforces the semantics of `value`, `operator`, `levels` and `numbered` through worked KPI examples (Profit = Revenue − Costs), which aids comprehension but adds little the schema doesn't already say. Baseline 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 and resource ('Generate a slide-deck-quality issue tree or driver tree') and then describes the concrete visual output: key question on the left, broken into drivers/sub-drivers/hypotheses in columns of rounded boxes with elbow connectors. It actively distinguishes itself from siblings, naming mind map and org chart as the wrong tools for this job.

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 enumerates when to choose it (consulting issue trees, MECE breakdowns, hypothesis trees, KPI/value/driver trees, root-cause and problem trees) with the governing rule 'anything where a parent is logically made up of its children'. It also names what to use instead and the condition that selects it: mind map for loose brainstorms, org chart for people/reporting lines.

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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds substantial context beyond that: red/blue flagging with ↑/↓, US vs SI ranges overridable per value, a plain-text companion version for notes, a link-based delivery model where data rides in the URL, and a privacy warning never to include patient identifiers. It also discloses the "drawing aid, not clinical decision support" framing and the Edit-link adjustability. This is rich, non-redundant behavioral disclosure.

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?

It is a single dense paragraph, front-loaded with purpose, then features, routing, and constraints — a sensible order. It runs long and repeats the "drawing aid, not clinical decision support" line already present in the schema description, but nearly every sentence carries actionable information for the caller.

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 generate-an-image tool with a rich input schema and no output schema, the description covers what matters: what gets produced, that a link (not inline image) is the deliverable, that a plain-text version is included, flagging behavior, and privacy constraints. Nothing an agent needs in order to call it correctly is missing.

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%, so the schema already documents every parameter thoroughly, and the description's parameter notes (values as strings up to 8 characters, 1–8 panels) largely restate the schema. It does add some framing by describing the fishbone layout per panel type, but with the schema doing the heavy lifting a 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 opens with a specific verb+resource: "Generate clean lab fishbone diagrams (lab value skeletons)", then enumerates the exact skeletons (BMP/Chem-7, CBC, coags, LFT, ABG, Ca/Mg/Phos) and their layouts. It explicitly distinguishes itself from the sibling create_fishbone (Ishikawa cause-and-effect diagram), so an agent can tell them apart 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 states the selection condition plainly ("Choose it whenever lab results should be shown in fishbone form") and names the alternative and its exclusion ("not a cause-and-effect (Ishikawa) diagram, for which use create_fishbone"). It also gives operational guidance — infer missing details rather than asking, and always surface the image link — leaving little to inference.

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 safety (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds real operational context on top: hard limits (8 branches, 3 levels, 50 topics), the instruction to infer missing details rather than ask, that the user can adjust via an Edit link, and the persistence caveat that inline images cannot be saved. It could have stated whether exceeding limits errors or silently truncates (the schema says extras are dropped with a warning), but the behavioral picture is unusually 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?

Front-loaded with the core purpose and followed immediately by the use/don't-use decision, so scanning early yields the routing decision. Some visual flourish ("smooth tapered curves", the full list of use-case nouns) is longer than strictly needed but it is a design tool where output appearance informs selection, so little is truly wasted.

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 fully: it tells the agent to always return the image link, explains the link renders the exact chart on demand and can be pasted into slides or Markdown, and points at the Edit link for user adjustments. Combined with the stated structural limits, an agent has everything needed to call it and relay the result.

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; the description still adds value by telling the agent to nest sub-topics in `children`, to keep labels to a few words, and by stating limits (3 levels, 50 topics) that the schema's maxItems does not express. It says little extra about layout, palette, or credit beyond what the schema already documents.

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 ("slide-deck-quality mind map") and then describes the artifact concretely: a central topic pill with colour-coded branches and tapered curves. An agent can distinguish this from create_org_chart or create_process without opening the 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?

Explicitly lists when to choose it (brainstorms, idea/theme breakdowns, workshop outputs, feature/research groupings, unpacking ONE central idea) and names both the exclusion criterion (no order or reporting line) and the sibling alternatives with their selecting conditions: org chart for people/reporting, hub and spoke for peers of one centre, process or cycle when order matters.

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 (readOnlyHint, idempotentHint, openWorldHint=false) are consistent with a deterministic renderer, and the description adds substantial context beyond them: hard limits (60 people, 5 levels), the auto-stacking rule for 4+ leaf reports, automatic palette assignment per team, silent truncation/dropping behavior, and the operational warning that inline chat images usually cannot be saved so the image link must always be surfaced.

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 artifact, then alternatives, then data-shaping rules, then the image-link instruction — a sensible priority order. It is dense and multi-clause (roughly 150 words), but nearly every sentence carries an instruction the agent would otherwise get wrong; only the colour-automatic explanation slightly duplicates the schema.

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, but the description covers the return artifact (rendered chart at 2x PNG, plus a persistent image link) and the failure modes (truncation, dropped people, un-saveable inline images). For a nested-tree generation tool with 7 parameters, nothing an agent needs to call it correctly is missing.

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 adds real guidance: `color` is an override only because team colour propagates automatically from the root's direct reports, and `palette` should carry the user's brand colours when named. It doesn't add anything for `width`, `layout`, `title`, or `credit`, which the schema already covers well.

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 artifact ('Generate a slide-deck-quality org chart') and immediately describes the rendered output — people cards with name/role/initials, elbow connectors, two orientations. It explicitly separates itself from the sibling shapes ('use a mind map instead... hub and spoke for one centre with peers'), so an agent can pick it without opening the 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 an explicit selection rule ('Choose it whenever the point is WHO reports to or works with whom') with concrete use cases (reporting lines, project teams, governance structures) and names two alternatives with the conditions that favor them. Also tells the agent how to behave when data is incomplete ('Infer missing details rather than asking').

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 read-only, idempotent, and closed-world behavior, but the description adds important operational context: infer missing details instead of asking, users can adjust via the Edit link, and the image link must always be given because inline chat images may not save. These are non-obvious behaviors not captured in annotations or schema.

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?

Despite being detailed, it is front-loaded with the core purpose and then organized into when-to-use, alternatives, limits, behavioral guidance, and output-link handling. Every sentence serves a clear selection or invocation purpose.

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, but the description explains the generated chart, its limits, the Edit link, and the essential image-link return behavior. Combined with rich parameter descriptions, an agent has everything needed to call and use the 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%, so the schema already documents all seven parameters thoroughly. The description reinforces phase count, bullet limits, timing, and the highlight option, but does not add substantial parameter semantics beyond what is already in 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 uses a specific verb and resource ('Generate a slide-deck-quality chevron process diagram') and explicitly distinguishes the tool from timeline, cycle, org chart, and mind map alternatives. An agent can identify the exact chart type this tool creates without opening the 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 concrete use cases ('our approach', delivery phases, sales/onboarding process, short linear sequences where order matters) and explicit alternatives for adjacent situations: timeline for dates/overlaps, cycle for loops, org chart/mind map for branching. Limits and preferred phrasing are also stated.

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 only cover the read-only/idempotent profile, and the description adds real behavioural context beyond that: the 2–8 layer cap with extras 'dropped with a warning', label-fit behaviour (names inside the shape or beside it with a leader line), auto-sizing, and the critical fact that inline chat images usually cannot be saved so the link must be given. That is exactly the non-obvious behaviour an agent needs.

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 purpose, then usage routing, then limits, then delivery instruction — a sensible priority order. It runs long and repeats the 2–8 layer limit that the schema already enforces via minItems/maxItems, which costs it 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?

No output schema exists, and the description compensates fully by explaining what the agent gets back (an image plus an Edit link) and how to hand it to the user. Nothing an agent needs to call this correctly or report the result is missing.

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 authoring guidance the schema lacks — names to one to four words, details to one short sentence, layers listed top-to-bottom with opposite meaning in each mode. It reinforces the mode/ordering semantics that are the most error-prone part of the call.

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 ('Generate a slide-deck-quality pyramid or funnel') and immediately defines both modes with concrete use cases (hierarchy of needs, sales funnel). An agent can distinguish this from create_process, create_cycle, create_hub_spoke and create_timeline without opening any 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 selection criteria: 'Choose it when items stack in a ranked order or narrow down stage by stage', followed by named alternatives and the condition that selects each (process = equal-weight phases, cycle = loop, hub and spoke = parts around a centre, timeline = dates matter). It also states operational policy — infer missing details rather than asking, and always surface the image link.

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?

The annotations declare a safe, idempotent read with no external world access, and the description is consistent with that while adding substantial operational context: hard limits (30 items, 40-character names, 6 bullets per quadrant), automatic non-overlapping label placement, tinting from the first palette colour, and an always-emit-the-image-link instruction with the reason (inline chat images cannot be saved). It also points the user to the Edit link, which the agent could not infer from the 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?

The purpose is front-loaded and the closing image-link instruction is well placed, but the middle is a dense run-on block that re-enumerates preset axis and quadrant details already fully specified in the preset enum. Those sentences do not earn their place twice and make the definition harder to scan than it needs to be.

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 correctly covers output delivery (always return the image link, why inline images fail, pasteability into slides or Markdown) and the edit path. For an 11-parameter, nested-schema tool this is nearly complete; only the exact response payload shape is left implicit.

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 schema already carries the per-field detail; the description still adds routing value the schema does not, such as 'give revenue as size' for BCG bubbles and 'rename the axes to your attributes' for perceptual maps, plus 'an omitted preset means none'. It does not add much on width, palette, or reverse-flag behaviour beyond the schema, so it sits above the 3 baseline but not at the top.

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 opening sentence names the concrete artifact ('slide-deck-quality 2×2 matrix, the classic consulting quadrant slide') and immediately distinguishes the two output shapes: items plotted as dots versus bullets per quadrant. It stays clearly distinct from siblings like create_harvey_matrix and create_swot, which are named later.

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 states when to choose it ('prioritise or position things on two dimensions: tasks, initiatives, features, products, brands, stakeholders or risks'), gives a preset-to-use-case mapping (impactEffort for quick wins, bcg for growth-share, eisenhower for to-do list), and names three alternatives plus the condition that selects them (Harvey balls for scoring against criteria, create_five_forces, create_swot). This is about as complete as routing guidance gets.

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 readOnly/idempotent/closed-world, and the description adds real context beyond them: the amber per-row rule notes, that broken rules surface in a `warnings` field, hard limits of 1–10 roles and 30 rows, and that the chart is editable via an Edit link. The one gap is that it never says how the image link/return value is shaped, though it does insist the link be given to the user.

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?

Purpose, usage, exclusions, limits and the mandatory image-link instruction are all front-loaded and in a sensible order. It is a dense single block rather than scannable sections, and the RACI letter definitions repeat what the schema already says, which costs some tightness.

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 9-parameter generative tool with no output schema, the description covers the shape of the artifact, validation behavior and warnings, size constraints, styling hints, and the required follow-up of surfacing the image link. Nothing an agent needs to call it correctly appears to be missing.

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; the description still adds meaning by explaining the A/R combined owner case, that `model: "RASCI"` adds S, and that `type: "section"` rows are full-width headings with ignored cells. It does not, however, cover width/palette/credit/legend, which the schema alone must carry.

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 ("Generate a slide-deck-quality RACI matrix") and then describes the actual artifact: rows are tasks, columns are roles, cells are letter chips with R/A/C/I, plus optional section rows. It explicitly distinguishes itself from siblings (Harvey ball, org chart, timeline), so an agent can pick it 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?

Names concrete use cases (project roles, PMO governance, onboarding/handover, any "who does what" slide) and explicit when-not cases with the correct alternative tool for each. It also gives an operating rule — infer missing details rather than asking — which removes a common decision point.

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?

The description adds substantial behavioral context beyond the annotations: it discloses the rendering layout, warns that inline chat images are not saveable, instructs the agent to always provide the image link, notes the Edit link, and tells the agent to infer missing details rather than asking. These details are not repeated from the annotations or schema and materially affect correct invocation and delivery.

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 long but front-loads the core purpose and then systematically covers use cases, exclusions, limits, and output handling. Every sentence contributes useful information, though the usage-alternatives sentence is dense and could be tightened. For a 14-parameter visual generator, the length is largely justified.

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 the tool's complexity, absence of an output schema, and 14 parameters, the description is complete enough for correct use. It covers what the tool produces, when to use it, limits, alternatives, omitted-detail behavior, and how to deliver the output link. Nothing essential is missing.

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%, so the schema already provides detailed semantics for all 14 parameters. The description reinforces the step/item limits, optional process name, and start/end boundaries, but it does not mention several parameters such as width, colors, palette, credit, or numbered. Baseline 3 is appropriate because the schema is doing the heavy lifting.

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 and resource — generate a SIPOC diagram — and explains its exact visual structure (five columns, chevrons, stacked cards, numbered step boxes). It distinguishes the tool from siblings by naming chevron process, issue tree, and timeline as alternatives. An agent can identify this tool without opening the 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 use cases (Lean/Six Sigma scoping, DMAIC Define, process-improvement kick-offs, ISO documentation) and explicit alternatives to choose instead for adjacent needs: chevron process for simple phase sequences, issue tree for cause breakdowns, timeline when dates matter. The routing logic is clear and actionable.

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 closed-world, so the safety profile is covered; the description adds genuine behavioral context on top: hard limits (8 bullets of 3–8 words, 1–3 word column names, one-sentence conclusion), the instruction to infer content rather than interrogate the user, defaults that change with palette overrides, and the builder Edit link for post-hoc adjustment. The only omission is that it never states what the tool actually returns as a payload (image URL vs markdown vs file), which matters since there is no output schema — it only instructs the agent to surface "the image link".

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 what the chart is, then routing, then limits, then output instructions — a sensible priority order for an agent. It is dense and some visual styling detail ("softly tinted panel", marker glyphs) is decorative rather than decision-relevant, and the return-link instruction repeats itself, but no sentence is wholly wasted.

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 12-parameter, zero-required rendering tool with nested objects and no output schema, the description covers the gaps that matter: content inference policy, per-column bullet limits, color/label override semantics, and how to deliver the result to the user. Nothing an agent needs to compose a correct call and present the artifact is missing.

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; the description earns more by explaining cross-parameter behavior the schema states only thinly — that `order` must match the user's written order with Continue always last, that `labels` renames rather than replaces columns, and that a custom `palette` remaps colors left-to-right instead of the default red/emerald/sky. Length and phrasing guidance ("3–8 words", "1–3 words read best") connects schema maxLength constraints to practical use.

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?

Opens with a concrete verb and artifact ("Generate a slide-deck-quality Stop Start Continue chart") and specifies its structure: three equal columns, per-column colors/markers, up to 8 bullets, optional subject and conclusion band. Sibling differentiation is explicit — create_swot, Harvey ball matrix, and mind map are each named with the scenario that selects them.

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?

States positive triggers precisely ("sprint and project retrospectives, team or manager feedback, and reviews of a process, project or habit") and then gives explicit exclusions with alternatives: create_swot for strategic company/product assessment, Harvey ball matrix for scoring options, mind map for open-ended brainstorm. An agent can route between four related chart tools without opening another schema.

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 and idempotentHint, and the description adds real behavioral context beyond them: inference is expected rather than clarification questions, empty `strengths` is legal, and the user can adjust afterward via the builder Edit link. The operational rule about always surfacing the image link — because inline chat images cannot be saved — is a genuinely non-obvious behavioral detail. It stops short of stating what the tool returns (inline render vs. URL vs. both) which is the one loose end.

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?

Purpose and alternative routing are correctly front-loaded, but the body is a single dense paragraph with decorative wording ("softly tinted panel with its big coloured letter", "slide-deck-quality") that costs tokens without helping invocation. The high-value operational rules — inference over questions, the mandatory image link — are buried mid-paragraph and at the very end rather than surfaced structurally.

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 12-parameter tool with a nested colors object, no output schema and no enums, the description covers what matters: required vs. optional quadrants, content length limits, inference policy, and post-generation handoff. The one gap is that with no output schema, the description never states the shape of the response it insists the agent share, so the agent must infer what the "image link" is a field of.

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%, so the baseline is 3 and the bar for credit is higher. The description does add content guidance the schema lacks — infer 3–5 bullets per quadrant, keep them roughly 3–8 words, one-sentence conclusion, fill all four quadrants — which is useful. But it never touches the layout parameters (width, colors, palette, labels, credit, title, subject) that make up most of the 12-parameter surface.

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 opening sentence gives a specific verb and deliverable ("Generate a slide-deck-quality SWOT analysis") and then defines the exact output artifact — a 2×2 grid with named quadrants and their positions. It explicitly names the sibling tools it is not (create_five_forces, the Harvey ball matrix, an issue tree), so an agent can route on name alone.

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 enumerates the subjects it fits (company, product, team, project, person) and the use cases (strategy, business-plan, marketing, coursework), then names three alternatives with the condition that selects each: five forces for industry-level pressure, Harvey matrix for scoring options against criteria, issue tree for decomposing one problem. This is the explicit when/when-not/alternative pattern.

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 only declare it as a safe, idempotent, non-open-world read; the description adds the operational layer annotations cannot: hard limits (2–52 columns, 100 rows), the 0.25 duration milestone trick, an instruction to infer rather than ask, the presence of an Edit link in the builder, and the critical 'ALWAYS give the user the image link' post-call instruction with the reason inline images cannot be saved.

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 concrete output description, then selection guidance, then limits, then the link instruction. Dense but every sentence carries information; the image-link sentence is long but justified by its importance.

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 chart generator with no output schema, the description covers what is drawn, hard limits, how to handle missing input, and what to do with the returned artifact. Nothing an agent needs to call it correctly or hand off the result is missing.

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; the description still adds cross-parameter meaning by tying duration 0.25 to milestone diamonds and tying column counts to the stated limits. It does not walk through the remaining parameters (palette, credit, labelsInBars, width), which the schema already covers well.

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 ('Generate a slide-deck-quality Gantt timeline') and describes the visual output precisely: task bars, milestone diamonds, numbered time columns, section bands. It also names the sibling it is not (process diagram), so an agent can distinguish it from create_process 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 explicit positive cases ('project plans, roadmaps, launch schedules and anything where WHEN each piece of work happens is the point') and an explicit exclusion routed to an alternative ('use a process diagram instead when only the order of phases matters'). That is the full when/when-not/alternative triad.

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