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

readOnlyHint=true and openWorldHint=false already establish this as a side-effect-free, non-networked read. The description adds the content scope of the response, which is modest value, but says nothing about auth, caching, or limits, and since an output schema exists the return enumeration is partly redundant. Adequate but not rich.

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?

Three short clauses with the subject (FAF format info) front-loaded and the usage cue trailing. The first clause and the second sentence overlap slightly by both stating that format metadata is returned, a minor redundancy in an otherwise tight entry.

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 informational tool with an output schema covering the return shape, the description covers what the tool is and when to reach for it. Nothing needed to invoke it correctly is missing, though it could say a bit more about what distinguishes it from the other format-related siblings.

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 there is no parameter semantics for the description to clarify; the baseline for a no-arg tool is 4. Nothing in the description misrepresents the empty input contract.

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 names a specific resource (the FAF format) and enumerates what the tool returns: IANA registration, version, ecosystem, server version, and available MCP bridges. That is enough to distinguish it from data-manipulation siblings like faf_read, faf_validate, or faf_migrate, though no sibling is named 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?

"Use this when users ask what FAF is or how it connects to other AI platforms" gives a clear triggering context rather than leaving usage implied. It stops short of naming alternatives (e.g. faf_model or faf_discover for deeper spec detail) or stating when not to use it, so it falls just short of a 5.

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

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.

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description usefully elaborates beyond them: it lists the manifest files scanned, the fact that docker-compose images and Makefile/justfile targets are mapped, and that it only fills empty slots rather than overwriting. That last point is meaningful behavioral context for a mutation tool, though permissions/auth and any failure behavior remain unstated.

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?

Three front-loaded sentences with no filler; the mechanism and the create-or-fill outcome are stated up front. The middle sentence is dense with examples but every clause adds signal.

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?

An output schema exists, so return values need no elaboration, and the detection mechanics are well covered. The definition is still incomplete for a writer tool with 0% parameter coverage and heavy sibling overlap: it does not resolve how path/directory interact or when to prefer this over faf_init/faf_discover.

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%, so the description carries the full burden, yet it never mentions the two parameters. Crucially, the 'path' default ('project.faf') versus 'directory' ('.') distinction is ambiguous and undocumented, leaving the agent to infer which one governs where the file is written.

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?

It names a concrete verb (auto-detect + author/update) and resource (.faf file) and describes the mechanism in detail. The gap is sibling differentiation: faf_init and faf_discover plausibly overlap with this, yet the description never says how faf_auto differs from them, so an agent must guess.

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?

Usage is only implied through the create-or-fill branch ('Creates a new .faf if none exists, or fills empty slots in an existing one'), which is genuinely informative. But there is no explicit when-to-use vs faf_init/faf_discover/faf_read, and no exclusions or prerequisites stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safe read-only profile is covered. The description adds the shape of what comes back (project info, stack, instructions, score), but since an output schema exists this adds limited behavioral value and it discloses no side-effect or edge-case behavior.

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 tight sentences that front-load the core action and then the return content, with no filler. Efficient and well-ordered, though the second sentence could be slightly leaner.

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 read-only context-fetching tool with an output schema, the description covers what it does, what it returns, and a usage context, so an agent can call it correctly. The only notable gap is guidance on the path parameter and explicit differentiation from sibling retrieval tools.

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 (default 'project.faf') is never addressed in the description. The phrase 'from a .faf file' faintly implies path targets a .faf file, but the description does not compensate for the undocumented parameter or explain acceptable values.

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?

States a specific verb (Get) and resource (Gemini-optimized context from a .faf file), and enumerates the sections returned (project info, stack, instructions, score). It partially differentiates from siblings by noting it avoids 'reading the full .faf structure', but does not clarify how it differs from close siblings like faf_gemini or faf_read.

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?

'Use this to quickly understand a project without reading the full .faf structure' gives a clear use case and implicitly contrasts with faf_read. However, no explicit alternatives are named and no when-not-to-use condition or prerequisite is stated, leaving the routing to inference among 12 siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral detail: the search proceeds upward from start_dir through parent directories, clarifying that this is not a flat directory lookup. It omits not-found behavior and search limits, so not a 5.

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?

Three short sentences, zero filler, front-loaded with the core action and finishing with the routing hint. Every sentence earns its place.

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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. Purpose, mechanism, and ordering relative to faf_read are all present. What is missing is failure semantics (no .faf found) for a discovery 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 coverage is 0% and start_dir has no schema description, so the description must carry the load. It does explain that start_dir is the origin of an upward traversal, giving the parameter real meaning. It omits the '.' default and path-format expectations, so it only partially compensates.

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?

States a specific verb and resource ('Find .faf files') plus the exact mechanism ('walking up from start_dir') and target artifact ('project.faf'). It explicitly names the sibling faf_read, so an agent can distinguish it without inspecting either schema.

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?

Gives explicit workflow guidance: 'Use this before faf_read to locate the file automatically,' which tells the agent when this tool is the right choice. It does not state exclusions (e.g., what to do if no file exists or when to skip discovery), 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.

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

Annotations already declare non-destructive and idempotent, but the description adds real substance beyond them: it discloses that output is injected as a faf-managed block, that hand-written content is preserved, and that re-running updates the block in place. This tells the agent exactly what is and is not overwritten, which is the key behavioral risk for a write 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?

Front-loaded correctly: the first clause gives verb, artifact and the non-destructive guarantee. The parenthetical listing of GEMINI.md sections is somewhat dense and partly decorative, but every sentence still earns its place.

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?

An output schema exists, so return values need no explanation, and the annotations plus description together cover the safety and idempotency profile well. The only real gap is the undocumented 'path' parameter, which is low-risk given it is optional with a default.

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?

There is a single parameter, 'path', with 0% schema description coverage, and the description never mentions it, its expected format, or that it defaults to project.faf. The phrase 'from a .faf file' hints at the input but adds no syntax or resolution detail, so the schema carries an undocumented parameter with no compensating explanation.

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?

States a specific verb and artifact: 'Export and write GEMINI.md from a .faf file.' It also names what convention the output follows and equates itself to a known CLI command, so the purpose is unambiguous. It does not, however, differentiate itself from the likely sibling for other agent files (e.g. faf_agents), leaving the agent to infer the routing.

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?

Usage is implied rather than stated: this is the tool for producing GEMINI.md for Gemini CLI, but the description never says when to pick it over siblings like faf_agents or faf_context. There is no exclusion or precondition guidance, so the agent must infer the choice from tool names alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=false, so the safety profile is known. The description adds genuinely new behavior: the no-clobber rule on existing files and the path confinement to cwd / FAF_ALLOWED_ROOTS, which is a sandbox constraint the annotations do not express.

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?

Four short sentences plus a parenthetical constraint; the core action and output are front-loaded and each sentence carries a distinct fact (what it writes, the no-overwrite rule, the path sandbox). Nothing is padded, though the constraint sentence could be tightened.

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?

An output schema exists, so return values need not be described, and the description covers the mutation's side effects and path safety. Complete enough for a 4-param optional-only tool; only parameter defaults and error behaviour on a blocked path are left implicit.

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 0%, so the description must compensate, and it largely does: it names name, goal, and language as the file's content and addresses path both via 'the path is confined to the project root' and the file it writes. It does not explain the defaults or accepted value formats, so it is not fully compensatory.

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?

States a specific verb and resource ('Create a starter .faf file') and names the exact contents (project name, goal, language) plus the output artefact (valid FAF YAML with all required sections). It also routes the agent away from itself toward the sibling faf_discover, so it is distinguishable from the other faf_* tools without opening a schema.

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?

Gives an explicit when-not ('Will not overwrite an existing file') and names the alternative to use for the check ('use faf_discover first'). There is no guidance on when this is preferable to other creation/config siblings such as faf_auto or faf_migrate, but the main precondition is covered.

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

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

Annotations declare destructive=true/false readOnly, and the description adds substantial context beyond them: it names exactly what changes (faf_version bump, section roots created, re-serialization), what is preserved (values, legacy slot aliases), what is irreversibly lost (YAML comments and formatting), and how to preview via dry_run.

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?

Front-loaded with the primary action, followed by the precise transformation details and caveats. Dense but every sentence carries distinct information — no filler or repetition of the name.

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?

An output schema exists so return shape needn't be described. The description covers mutation scope, data-loss caveat, idempotency-adjacent claims, and the dry-run escape hatch, leaving nothing an agent needs to call it safely.

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 0% and neither parameter is described in the schema, but the description explains the non-obvious dry_run semantics ('preview'), which is the parameter whose behavior actually matters; path is only implied via the .faf file reference.

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?

States a specific verb (migrate) and resource (.faf file) plus the target version (3.0), and its scope (version + structure only) clearly separates it from siblings like faf_init, faf_validate, and faf_score.

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?

Gives a clear condition of use (moving a file to the current format version) and an operational hint ('Pass dry_run=true to preview'), but never names an alternative tool or states when NOT to use this one.

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

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

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds real value: it explains the return is a complete realistic project.faf covering all 33 slots, including 'slotignored' semantics for non-applicable slots. It omits any rate limits or auth notes, but for a read-only reference tool this is solid disclosure.

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?

Front-loaded with the core action, then adds scope, usage, and the no-argument behavior. Four sentences, each adding distinct information, though the 'shows exactly what 100% looks like' clause is mildly redundant with the Trophy-scored framing.

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?

An output schema exists, so return values need not be detailed, and the description still characterizes the returned file usefully. For a single-parameter read-only tool it covers purpose, usage, return shape, and no-arg behavior, with only the parameter's value format 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?

Schema description coverage is 0% for the single project_type parameter, so the description must compensate. It explains the meaningful behavior — omitting the argument lists all 15 project types — but never states the expected value format or enumerates the valid types, leaving the parameter partially opaque.

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?

States a specific verb and resource: 'Get a 100% Trophy-scored example .faf file for a specific project type', and clarifies it returns a complete project.faf filling all 33 scored slots. The purpose is unambiguous, but it never explicitly contrasts itself with siblings like faf_read or faf_init, so it stops short of a 5.

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?

'Use this as a reference when building or improving a .faf file' clearly frames when to reach for this tool, and 'Call without arguments to list all 15 available project types' gives the discovery path. It offers no exclusions or named alternatives, so it lacks the explicit when-not guidance of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful read-behavior detail (it returns the full parsed structure, not a partial view), but says nothing about failure modes such as a missing or malformed .faf file, which matters for a path-based reader.

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?

Three short sentences, front-loaded with purpose and followed by return content and usage ordering. The return-content sentence partially duplicates the output schema, but no sentence is filler.

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?

An output schema exists, so return values need not be spelled out, and the tool has one defaulted parameter and a covered safety profile. The main omission is edge-case behavior when the target file is absent or invalid.

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% for the single 'path' parameter, and the description only obliquely implies it by saying '.faf file'. It never explains the default (project.faf), path form, or resolution rules, so the description does not compensate for the schema gap.

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?

States a specific verb and resource ('Read project DNA from a .faf file') and even summarizes the returned structure. It does not differentiate itself from the many sibling tools (faf_stringify, faf_validate, faf_model), so an agent must infer the boundaries.

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?

'Use this as the first step to understand any FAF-enabled project' gives clear when-to-use context and establishes the tool's entry-point role. It names no exclusions or alternatives, so an agent is not told when another sibling is preferable.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so safety profile is already covered. The description adds useful scope ('quick', 'status check' vs error-detail path) and names the scoring engine, but doesn't disclose the return shape beyond the three fields, and an output schema exists anyway. Modest added value over 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?

Two tight sentences; the purpose is front-loaded and the routing instruction follows immediately. No filler, no repetition of the title.

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 simple single-param read-only status tool with an output schema, the description covers purpose and sibling routing, which is most of what's needed. The gap is the undocumented 'path' parameter, whose 0% schema coverage leaves an agent guessing about valid inputs.

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?

Only one optional parameter (path) with a default of 'project.faf', but schema description coverage is 0% — the schema gives no hint what 'path' points to or its format. The description does not compensate; it never mentions path, accepted file locations, or what happens if omitted/defaulted.

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?

Clearly states a specific verb+resource: 'Mk4 score check' returning score, tier, and slot counts. Distinguishes itself from sibling faf_validate by routing error-detail needs elsewhere. Not a 5 because 'Mk4 always-33 scoring engine (faf-kernel parity)' is jargon that may be opaque to a first-time agent, but the core purpose is legible.

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?

Explicitly says 'Use this for status checks; use faf_validate when you need error details' — names the alternative and the condition that selects it. This is exactly the when/when-not routing an agent needs.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine process detail ('Reads the file, parses it, then re-serializes'), but says nothing about failure behavior on malformed YAML or path resolution. With annotations handling the read-only story, a 3 is fair.

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?

Three brief, front-loaded sentences with no filler. Slight redundancy between the second and third sentences, which restate the display/edit intent alongside the mechanics, but it is efficient overall.

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?

An output schema exists, so return values need not be spelled out, and the operation is a simple single-param read. The main gap is sibling differentiation: the description never clarifies why an agent should choose faf_stringify over faf_read, which matters given twelve related tools.

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?

One parameter ('path') with 0% schema description coverage and a default of project.faf. The description only hints at it via 'Reads the file', never naming the parameter or explaining the default or accepted path forms. Marginal value over the bare schema.

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?

States a concrete verb+resource ('Convert parsed FAF data back to YAML string') and the pipeline that produces it. It is distinguishable from read-only siblings like faf_read, though it never names one directly. Minor tension: it claims to convert 'parsed FAF data' while the third sentence reveals the input is a file path.

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?

Offers two use contexts ('displaying the raw .faf content or preparing it for editing'), which implies when to reach for it. However, it gives no when-not guidance and never contrasts against faf_read or faf_model, which an agent must otherwise infer.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so the agent already knows this is a safe, local read. The description adds useful behavioral nuance by categorizing output into errors (must fix) and warnings (should fix), but it doesn't expand on whether validation can fail, how deep the checks go, or any file prerequisites. With annotations covering the safety profile, a 3 is appropriate.

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?

Three tight sentences, front-loaded with the result of validation, then output structure, then usage. No filler or redundancy; every sentence is informative.

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?

An output schema exists, so the description needn't detail return values, and it correctly sketches them anyway. It covers purpose, output categories, and when to run it. The only minor gap is not relating it to sibling tools like faf_score, but for a single-param read-only validator it is sufficiently complete.

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 0% and the single 'path' parameter has a default but no description in the schema. The description says 'a .faf file' but does not explain the path parameter, its default, or expected format. It adds only marginal meaning, so baseline 3 (one param, implicit scope) is fair.

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 specific verb (validate) and resource (.faf file), and it names the concrete return values: score, tier, and issues. This distinguishes it from siblings like faf_score (which only scores) and faf_read, giving an agent a clear functional boundary without opening the schema.

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 explicitly says to use it 'after faf_init' and 'when checking if a .faf file meets quality standards', providing clear usage context and a workflow anchor. It doesn't name alternatives or state when not to use it (e.g., vs. faf_score), but the context is strong.

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