Draft an AGENTS.md

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

Annotations already declare readOnlyHint=true, idempotentHint=true and a closed world, and the description reinforces them with 'Does not write a file' rather than contradicting them. It adds real behavioral context beyond the annotations by disclosing the content provenance (repo facts, 'nothing invented') and the two-block output shape when a project.faf is present.

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?

It is a single front-loaded sentence with the verb and resource leading, and every clause carries information (provenance, quality tiers, no-write guarantee). The stacked parentheticals and BETTER/BEST framing make it denser to parse than it needs to be, costing it the top mark.

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 zero-parameter draft generator with no output schema or annotations about returns, the description supplies what the agent needs: the source of content, the no-write guarantee, and the file's managed-block structure. Details like draft length or how an existing AGENTS.md is handled are left unstated.

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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter semantics for the description to compensate for. It correctly omits any argument discussion rather than inventing options.

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 states a clear verb+resource: 'Author an AGENTS.md for this project and return the draft,' plus the key scoping fact that it 'Does not write a file,' which distinguishes it from save/write siblings. It never names the read/list siblings directly, so an agent must infer the boundary from the verb alone rather than being told explicitly.

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 a usable precondition ('BEST when a project.faf exists') and a fallback path when it doesn't, which is genuine conditional guidance. However, it frames these as output-quality tiers (BETTER/BEST) rather than telling the agent when to choose this tool over alternatives like read_agents_md or list_agents_md_sections, so usage is only implied.

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