Guided Interview

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so safety is covered structurally. The description adds real value beyond that: answers are written in place, an answered slot's existing value is replaced, invalid keys or non-text answers are refused with nothing written, and project.faf is created via faf_init/faf_auto if missing. That is meaningful side-effect disclosure for a mutating tool.

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?

Two long, densely nested sentences pack in every behavior but bury the critical read-vs-write fork mid-clause, so it is not front-loaded for quick scanning. The information is mostly load-bearing, but nested asides ('faf_auto writes it: its dry run, the one faf_formats shows') hurt parseability.

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?

With no output schema, the description carries the return-value burden, and it does state the return (the Table-of-8 plus score in read mode, the new score in write mode). It also covers creation side effects and refusal behavior. What is missing is any guidance on subsequent calls or the session-context effect of path beyond the schema note.

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% and both parameters are documented in the schema, so the baseline is 3. The description restates the slot-path→text answer shape and the refusal rule, but adds little syntax or format detail the schema does not already supply (its example values overlap the schema's own examples).

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 defines a specific dual-mode tool: read-only interview output (the Table-of-8 seeded from the goal with score) when no answers are given, and an in-place writer of answers into <folder>/project.faf when they are. It positions itself against siblings by naming faf_auto and faf_init as things it invokes and faf_formats as showing the dry run. However, jargon like 'Table-of-8' and 'the human half of project.faf' assumes familiarity, so an unfamiliar agent needs more parsing than ideal.

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 implicitly delineates when each mode applies (no answers = inspect, answers = write) and names the parent workflow (faf_init/faf_auto run first if project.faf is absent). But there is no explicit 'use this instead of X' routing or stated prerequisites beyond that, so the agent must infer when faf_go beats faf_auto or faf_score.

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