record_taste_decision

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

The description discloses important side effects beyond the raw annotations: recorded decisions evolve future get_taste_interview kickoffs, recurring choices become suggested defaults, and uncovered categories become new interview questions. This makes the persistent side effect of each record explicit and is not contradicted by the 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 description is long, but every sentence advances agent understanding: when to call, what to record, what the fields mean, and what happens afterward. It is front-loaded with the core recording action and the 'moment it is made' rule before moving to supporting details.

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 tool with 7 parameters, 4 required, and no output schema, the description covers the purpose, the triggers, the source values, the content requirements, and the downstream consequences. The missing response format is not a blocker because the tool's main value is the recorded side effect described clearly.

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?

Although the schema describes all parameters at 100% coverage, the description adds meaningful semantics with concrete examples and the causal consequences of dimension categories. It also explains what makes a record useful—user-overriding generated choices is a high-signal record—which goes beyond the schema's field names.

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 uses a specific verb—record—and clearly identifies the resource as the Taste Engine's learning loop for taste, direction, and design decisions. It distinguishes itself from generic decision or review tools by centering on taste-related decisions captured during real work, not just interview time.

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?

It gives clear timing guidance: record the moment a decision is made during real work, and record liberally because every committed decision is calibration data. It does not explicitly name a sibling alternative or call out when not to use the tool, so it stops short of a full 5.

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