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

Beyond the annotations, the description discloses important behavioral guarantees: illustrative inputs are 'labeled not-a-recommendation and is never applied silently', alternatives are 'ranked best-first by a checkable score', deltas name their baseline, projection-backed candidates link verifiable records, and exclusions are stated in the notes. This adds substantial transparency beyond the idempotentHint and destructiveHint 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 content is dense and all relevant, but the description is a single long paragraph with semicolon-separated details. A bulleted strategy list and separate behavioral notes would make it much easier to scan. It is front-loaded with the core purpose, but the structure does not support quick reference.

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 multi-strategy tool with no output schema, the description is unusually complete. It covers all seven strategies, their parameters and optionality, the ranked output format, evidence and baseline behavior, and important caveats like the illustrative asset-location set. An agent has enough information to invoke the tool correctly and interpret its results.

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?

With only 29% schema description coverage, the description takes on the burden of documenting strategy-specific parameters and largely succeeds: it enumerates params for each strategy, including roth-ladder candidates, ss-claiming candidateAges, asset-location tax rates, tax-loss-harvesting rates, annual-gifting counts, and pension-election options. It does not fully explain shared fields like profile or assumptions, but the ambiguous strategy params are well covered.

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 and resource: 'Run a Household Coordination Engine strategy on a stored household' and clearly states the output: 'a ranked decision object with evidence records.' The strategy list and decision-object framing distinguish it from siblings like run_model, project_household, and narrate_decision.

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 clearly establishes the context: use this tool when you need to run one of the listed coordination strategies on a stored household and get a ranked decision. It does not explicitly name alternatives or exclusions, but the use case is concrete enough that an agent should not confuse it with generic projection or narration tools.

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