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.