get_taste_interview

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

Goes well beyond the annotations by disclosing determinism, the depth-dependent output shape (5 core questions + more_questions vs a flat full list), per-question flags, the voice question's three registers, and an error condition ('throws naming get_taste_interview kickoff otherwise'). Despite that, the phrase 'throws naming get_taste_interview kickoff otherwise' is garbled and slightly obscures the exact error behavior; otherwise this is notably transparent.

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 a single massive block of text with deep parentheticals and run-on sentences, including a garbled clause ('throws naming get_taste_interview kickoff otherwise') that hinders skimming. While front-loaded with the 'START HERE' instruction, the lack of line breaks or focused headings makes even a slightly complex tool much harder to parse 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?

Despite having no output schema, the description covers the core return shapes (questions, more_questions, flat question list), the question structure (skippable, priority, required only for identity), the integration point with audit_taste, and the post-interview persistence step. Some edge cases like presentation of more_questions and exact error handling are only hinted at, but nothing is fundamentally 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 baseline is 3; the description meaningfully adds semantics by clarifying why the project parameter matters ('Include it so the interview can show any existing binding'), explaining mode:'refine' behavior (involves keep/tighten/replace), and detailing depth effect on the returned question shape. Not all parameters get equivalent depth, but the added value pushes it above baseline.

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 says exactly what the tool does with a specific verb and resource: 'returns a deterministic calibration interview.' It immediately establishes the new-project scope ('START HERE on a NEW project') and the refine-already-calibrated alternative, differentiating itself from the sibling tools it pairs with (bind_taste_surface for persistence, audit_taste for later audits).

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 is explicit about when to use it: 'Run this BEFORE the first audit_taste on any project that has no binding yet', 'START HERE on a NEW project', and use mode:'refine' instead of starting over when an already-calibrated user dislikes output. It also prescribes the follow-up action (persist with bind_taste_surface), leaving no ambiguity about the workflow.

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