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

Annotations already declare readOnly, idempotent, closed-world, so the safety profile is covered. The description adds substantial non-obvious behavior: two fixed closing blocks always returned, consult status replaces architecture for certain inputs, and heavy output content restrictions (no provider names, bands not point prices).

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 tool behavior ends early; the remainder is a repetitive wall of output-governance rules (never name a provider, bands never point prices, never state floors, etc.) that restate the same prohibition multiple ways. The description is dominated by compliance rules rather than tool selection guidance.

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 does enumerate the major return sections (components, routes, reasoning, economics bands, risks, sequence, two closing blocks), which fills some of that gap. But parameter documentation remains thin for a 14-param tool and missing when-to-use against recommend_stack.

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 50%, so half the 14 parameters rely on the description. It only states that it takes 'the same business profile as assess_business' and names economics bands, without explaining regions, licences, engagement_ref semantics, or treasury_needs beyond what the schema already says. Adequate but far from full compensation for the coverage gap.

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: it produces an architecture (rails, order, dependencies) from a business profile. It distinguishes itself from assess_business (step 1) and compare_stack_scenarios (variation testing), but the self-congratulatory 'richest tool on this server' is unhelpful filler.

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 positions itself as 'architect step 2' after assess_business, and names compare_stack_scenarios as the variation-testing alternative. Also routes consult-tier verticals and prohibited region combos to a consult status. Lacks when-NOT-to-use for recommend_stack, which overlaps in the same family.

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