Faf Agents

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

Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description usefully adds that it preserves hand-written content, injects a faf-managed block, and never overwrites the file, which clarifies the mutation behavior beyond 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 front-loaded with the core action and then adds useful behavioral detail. It is slightly repetitive around non-destructive behavior, but every sentence contributes relevant context.

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 an output schema present and annotations covering safety and idempotency, the description supplies enough behavioral context for correct invocation. The main remaining gap is the undocumented path parameter, but overall it is complete for this tool.

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 0% and the single path parameter is not mentioned by name or default in the description. The phrase 'from a .faf file' hints at the input but does not compensate for the missing parameter documentation.

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 clearly states a specific verb and resource: export/write AGENTS.md from a .faf file. It is specific enough to distinguish from most siblings, but it does not explicitly differentiate itself from other faf_* tools such as faf_stringify or faf_context.

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 implies when to use it by naming the output artifact and noting that re-running updates the block in place. However, it gives no explicit when-not conditions or alternative sibling tools to use instead, leaving usage guidance at an implied level.

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