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

Annotations already say readOnly/idempotent/non-destructive, and the description adds substantively: nothing is stored, no model is called, the tool validates structure not facts, and a bad document returns the spec's VALIDATION_FAILED list to fix. It also discloses rendering differences between MCP Apps hosts and plain text, the 'Composed by your assistant' labelling, and that only Field Guide pages are accepted as sources — all consistent with openWorldHint=false.

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 core purpose and the trigger list are front-loaded in the first two sentences, and almost every clause carries information an agent needs. However it is a single dense paragraph that chains card types, trigger phrases, sibling routing, Databricks sourcing rules, host rendering, and validation behavior — it would be more scannable as short labelled sections.

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 a rich annotation set, 100% schema coverage, and an output schema, the description covers everything the schema can't: when to pick it, what it does not do, prerequisite sourcing for Databricks questions, host-dependent rendering, and failure behavior. An agent has no open questions before calling it.

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 parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the most consequential constraint (sources must be Field Guide URLs, non-guide links are listed as not-from-the-guide) but adds no format or syntax detail for `document` or `title` beyond what the schema states.

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?

Starts with a specific verb and resource ('draws your answer as a card') and enumerates the concrete card shapes it produces (comparison with verdict, plan steps, calculator with sliders, quiz, table, Mermaid diagram). It also names the sibling tools it is not (explore_concept, decide, estimate_cost), so an 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?

Gives explicit trigger vocabulary ('compare', 'X vs Y', 'pros and cons', 'roadmap', 'show me', 'chart') plus a negative rule: don't answer with a long Markdown table or list. It also routes competing intents away by name ('a decision decide has a tree for, and a cost estimate_cost prices go to those tools first'), and gives a Databricks-specific prerequisite sequence (search_guide/get_chapter first, then cite URLs).

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