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

No annotations are provided, so the description carries the full burden. It implies a read-only informational operation via 'Returns metadata' and 'info', but does not explicitly state absence of side effects, required permissions, or rate limits. Adequate but not rich for a zero-param info 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?

Three short sentences, front-loaded with what the tool returns and followed by the usage trigger. Slight redundancy between 'FAF format info' and 'Returns metadata about the FAF format' but no filler sentences.

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 need not explain return values, yet it still states the key returned metadata. For a simple, zero-param info tool with no annotations, it gives enough for an agent to select and invoke it correctly.

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?

Zero parameters, so the baseline is 4 per rubric. The description adds no parameter semantics because none are needed or possible.

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 'Returns metadata' and resource 'FAF format, server version, and available MCP bridges', clearly distinguishing from write-oriented siblings like faf_init or faf_stringify. Does not explicitly name alternatives, but scope is clear enough for selection.

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 trigger: 'Use this when users ask what FAF is or how it connects to other AI platforms.' No when-not conditions or named sibling alternatives are provided, so it falls 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?

With no annotations provided, the description carries the full burden and does well: it declares non-destructive behavior, block-scoped injection that preserves hand-written content, idempotent re-runs, and the exact output sections authored. It stops short of stating auth/permission needs or failure modes if the file is missing or malformed.

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 export/authoring summary and the parenthetical section list is compact and informative. Mild redundancy: 'non-destructive' is asserted twice ('non-destructive' and 'it never overwrites your file'), slightly padding the ending.

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 behavioral contract (block injection, preservation, in-place update) is well covered for a file-mutating tool with zero annotations. The only real gap is the undocumented `path` parameter and 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?

Schema description coverage is 0% for the single `path` parameter, so the description must compensate; it only alludes to 'a .faf file' and never names the parameter, its default (`project.faf`), or accepted path formats. Partial coverage of a one-param tool, hence a middling score.

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/write AGENTS.md from a .faf file) and the mechanism (faf-python-sdk authoring, parity with `faf export --agents`), which clearly separates it from siblings like faf_stringify, faf_migrate, or faf_init.

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: it's the tool that produces/refreshes the AGENTS.md block, and re-running updates in place. But it never says when to prefer this over sibling tools (e.g. faf_init or faf_auto for the same file), nor any prerequisite such as a valid .faf existing.

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 no annotations, the description carries the full burden and does so reasonably well: it discloses the mutation profile (creates or updates a file), the non-destructive rule (only fills empty slots), and the sourcing method (facts from files, no hardcoded defaults). It omits permission requirements and whether existing populated values are ever overwritten, but the mechanism is unusually well described for an unannotated 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?

It is a tight, front-loaded paragraph: purpose first, then the detection mechanism, then the create-vs-fill behavior. The manifest list is slightly padded but each example adds useful specificity, so little is wasted.

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 explained, and the detection/mutation behavior is well covered. The main gap is the two undocumented parameters, which leaves the definition incomplete for a tool the agent must invoke with a file path and directory.

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% across two parameters, yet the description never mentions path or directory, their defaults, or how they interact (e.g. file name vs. working directory). The agent must infer everything from the raw JSON schema, so the description fails to compensate for the coverage 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?

The description gives a specific verb and resource: auto-detect project stack and author/update a .faf file, and spells out what it scans (package.json, pyproject.toml, docker-compose, Makefile). It is clear, but it never distinguishes itself from siblings like faf_init or faf_discover, which an agent would need to choose between.

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?

"Creates a new .faf if none exists, or fills empty slots in an existing one" gives one clear state condition, implying use when a .faf is missing or partially populated. However, there is no explicit when-to-use versus faf_init/faf_discover/faf_migrate, and no prerequisites or exclusions are 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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses the output shape (project info, stack, instructions, score) and that it reads rather than writes, but says nothing about auth, side effects, error behavior for missing files, or what happens with the default path.

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 the action and purpose. No filler. The 'Use this to...' sentence is slightly redundant with the earlier enumeration but earns its place by framing intent.

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 value details need not be described; the description still usefully summarizes sections. Missing the path parameter behavior and any file-not-found handling, but otherwise adequate for a simple read 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?

Only one parameter with 0% schema description coverage; the description never mentions the 'path' parameter, its default, or the expected .faf file format/location. With 1 param and low coverage, the description fails to compensate at all, though the surface area is small.

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 Gemini-optimized context from a .faf file', followed by an enumeration of what's returned (project info, stack, instructions, score). It does not, however, distinguish itself from siblings like faf_read, faf_gemini, or faf_score, which likely overlap in scope.

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?

Provides an implied use case ('to quickly understand a project without reading the full .faf structure'), which is useful framing. But it doesn't name which sibling to use instead for a full read (faf_read) or how it differs from faf_gemini, which is especially important given the overlapping sibling set.

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 no annotations, the description carries the full behavioral burden. It usefully discloses the search algorithm (ascend from start_dir through the current and parent directories) and the target filename (project.faf), implying a read-only operation. It does not say what happens on no match, whether multiple matches are returned, or whether traversal stops at a root, leaving real gaps.

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 with the core action front-loaded and the usage hint last where it belongs. Minor redundancy between 'walking up from start_dir' and 'searches the current directory and parent directories,' but no real waste.

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 one-parameter discovery tool with an output schema (so return format needn't be described), the description covers purpose, traversal semantics, and where it fits relative to faf_read. Missing only failure/no-match behavior and the parameter 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?

Schema description coverage is 0%, so the description must compensate for the single parameter. It explains start_dir as the origin of the upward walk, which adds meaning beyond the bare schema, but omits the default value ('.') and whether relative/absolute paths are accepted.

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 ('Find') and resource ('.faf files'), plus the exact traversal behavior ('walking up ... parent directories for project.faf'). It also names the sibling it precedes (faf_read), so an agent can distinguish it from faf_read without opening 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?

Explicitly states when to use it: 'Use this before faf_read to locate the file automatically,' which gives ordering relative to an alternative. It lacks any when-not condition (e.g., what to do if the file is already known), so it stops 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?

With no annotations, the description carries the full burden and does well: it discloses non-destructiveness, faf-managed block injection, preservation of hand-written content, and idempotent re-run behavior. Auth/prerequisite context is absent, but the behavioral profile is otherwise 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?

The core action is front-loaded in the first sentence, and details follow usefully. Some phrasing is dense/redundant (the parity clause plus the convention parenthetical), but every sentence adds real information.

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 explained, and the description adequately covers what is written and how it merges with existing content. Only the lone parameter's semantics are left under-specified.

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 with 0% schema description coverage. The description implies the .faf source ('from a .faf file') but never names or explains the `path` parameter, its default, or accepted values, so compensation for the coverage gap is only partial.

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 specific verbs and resource ('Export and write GEMINI.md from a .faf file') and the generated artifact's convention (hierarchical, @file-importable). It is distinguishable from siblings, though it does not explicitly contrast itself with any of them by name.

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 by the description ('in parity with faf-cli's `faf export --gemini`') but there is no explicit when-to-use vs alternatives guidance or exclusions among the many faf_* siblings. An agent must infer that this tool targets Gemini specifically.

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 no annotations, the description carries the burden and does well: it discloses that it writes a valid FAF YAML file with all required sections, refuses to overwrite existing files, and confines the path to the project root (cwd / FAF_ALLOWED_ROOTS). The only gap is the absence of any note on permissions or what the write returns, but the safety profile is well covered.

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, each carrying a distinct piece of load-bearing information (purpose, output validity, non-overwrite rule, path scope), with the primary action front-loaded. No 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 documented. The description covers purpose, safety behavior, and path scoping for a 4-parameter write tool, leaving only minor gaps around parameter defaults and privilege requirements.

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 maps three of four parameters (name, goal, language) plus the path constraint (root confinement). It adds real meaning beyond the bare schema, though it does not clarify defaults or that all four parameters are optional.

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: creates a starter .faf file and enumerates the fields written (project name, goal, language). It also names faf_discover as the pre-check sibling, giving partial differentiation from the large sibling set, though it does not contrast with close relatives like faf_auto or faf_migrate.

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 gives the when-not condition ('Will not overwrite an existing file') and routes to the alternative ('use faf_discover first to check'). This is clear conditional guidance, but it does not describe the general when-to-use case versus faf_auto/faf_migrate for starting a project.

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 no annotations, the description carries the full behavioral burden and does well: it discloses that it bumps faf_version, ensures section roots exist, re-serializes, preserves values, and offers dry_run previewing. It does not cover permissions, error handling, or whether migrations are idempotent, but the core effects are unusually clear.

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 main action, then adds necessary behavioral details in a compact paragraph. Every sentence adds useful context about scope, guarantees, and dry_run, with no 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?

The tool has moderate complexity with two parameters and an output schema, so return values do not need explanation here. The description covers the migration behavior, what gets modified, and what stays untouched, but could add a brief note on prerequisites or idempotency.

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 both parameters. The description explains dry_run ('Pass dry_run=true to preview') and implies the path is the .faf file to migrate, but it does not document the default filename or path format, so it only partially compensates for the missing schema descriptions.

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 and resource: 'Migrate a .faf file to the current format version (3.0)'. It adds concrete detail about what migration changes, which clearly distinguishes it from siblings like faf_init or faf_validate, though it does not explicitly name alternative tools.

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 the tool is useful ('Migrate a .faf file to the current format version') and mentions the dry_run preview option, but it does not explicitly say when to choose this tool over siblings or what conditions require migration versus validation.

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 no annotations, the description carries the full burden and it does disclose non-obvious behavior: the file fills 'all 21 scored slots' and an argument-free call 'list[s] all 15 available project types'. That empty-argument fallback is genuinely behavioral information the schema cannot convey. It stops short of stating the operation is side-effect-free or what an invalid project_type returns.

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, all front-loaded with the core output first and the no-argument behavior last. There is mild redundancy between '100% Trophy-scored' and 'shows exactly what 100% looks like', but nothing is wasted.

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-parameter fetch tool with an output schema present, the description covers selection, output nature, and the empty-argument mode, so an agent can call it correctly. The main omission is not distinguishing itself from the many sibling faf_* tools that also operate on .faf files.

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 parameter has no schema description or enum, so the description must compensate — and it largely does by explaining that project_type selects a project type and that the 15 valid values can be enumerated via a no-argument call. It does not specify the accepted value format (slug vs. label), leaving a small gap the agent must probe for.

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 gives a specific verb and resource ('Get a ... example .faf file') plus a clear scope ('for a specific project type'), so its purpose is unambiguous. It never names which sibling it complements (faf_init, faf_score, faf_validate), but against a 13-tool family that only costs it the top 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?

'Use this as a reference when building or improving a .faf file' supplies a concrete usage context, which is stronger than mere implication. However, it names no alternative and states no when-not-to-use condition, so it falls short of an explicit routing rule.

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 no annotations, the description carries the full burden. It implies read-only behavior ("Read") and discloses what is returned, but says nothing about failure modes (missing file, malformed .faf), permissions, or whether anything is written back, so an agent cannot fully predict behavior on edge cases.

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 the core action and return contents, then the usage hint. 'Project DNA' is mildly informal but not wasteful; nothing is padded.

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 still summarizes the parsed structure. For a one-parameter read tool this is nearly sufficient, with only the default-path behavior 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 'path' parameter, so the description must compensate and only partially does: it names the file type but never mentions that a path can be supplied or that it defaults to 'project.faf'. Calling the tool with no arguments is the common case and its behavior is never explained.

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 and resource (read project DNA from a .faf file) and names what it returns (project info, stack, preferences, scoring data). It does not explicitly differentiate itself from siblings that also read a .faf file, such as faf_validate or faf_score, 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 the first step to understand any FAF-enabled project' gives a clear sequencing/call-context directive rather than leaving usage to inference. However, it names no alternative (faf_validate, faf_score, faf_discover) and states no when-not conditions, so it lacks true routing guidance.

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?

No annotations are provided, so the description carries the full disclosure burden. 'Check' and 'returns' imply a read-only operation and it adds engine context (Mk4 Championship 21-slot), but it never explicitly confirms no side effects or write behavior. 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 sentences, front-loaded with what it returns before the routing guidance. Every sentence earns its place with no 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 needn't be re-explained. For a simple read tool the description is nearly complete, with the only gap being the undocumented path parameter and the absence of any explicit read-only confirmation.

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 there is one parameter ('path', default 'project.faf') that the description never mentions. The description does nothing to explain the path argument or its default, so it fails to compensate for the coverage 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 ('score check') and enumerates the return payload (score 0-100%, tier, slot counts). It names the sibling it is not (faf_validate), so an agent can distinguish it without opening 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?

Explicitly routes usage: 'Use this for status checks; use faf_validate when you need error details.' The alternative and the condition that selects it are both stated, leaving nothing to inference.

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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the internal pipeline ('reads the file, parses it, then re-serializes'), which is useful, but it omits whether the source file is modified, what happens if the file is missing or invalid, and any permission/auth requirements. The 'preparing it for editing' phrasing hints at a non-mutating return-only tool but never states it outright.

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 with the core action front-loaded and no filler. Efficient, though the second and third sentences could be merged without loss.

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 need not spell out return values, and it correctly summarizes the output as clean YAML. For a single-optional-parameter transform tool this is nearly sufficient; the only real gap is error/default-path behavior for the 'path' argument.

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 (default 'project.faf'). The description refers only to 'the file,' adding no default value, path format, or resolution semantics beyond what the bare schema already shows, so it fails to compensate for the coverage 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: 'Convert parsed FAF data back to YAML string,' which is concrete and distinguishable from read/validate/score siblings. It does not explicitly contrast itself with the closest sibling faf_read, so it falls short of the 5 bar.

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 usage contexts ('displaying the raw .faf content or preparing it for editing'), which implies when to reach for it. However, it never names alternatives (e.g., faf_read) or states when NOT to use it, so routing among the 13 siblings is largely left to inference.

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 no annotations, the description carries the full burden. It usefully explains that errors are must-fix and warnings should-fix and that messages are specific, but it never states that validation is read-only, that it touches no other state, or whether it can fail on a missing path.

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 the core action and output, then the error/warning distinction, then usage. Nothing is padded, though the return-value sentence is partly redundant given an output schema exists.

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 single-argument, non-destructive validation tool with an output schema, the description covers action, output shape, and trigger condition adequately. The only real gap is the undocumented path parameter.

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 one parameter with 0% schema description coverage, and the description never mentions 'path' or its default of project.faf. An agent must infer that the argument is a file path to the target .faf file.

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 gives a specific verb (validate) and resource (.faf file) and even names the outputs (score, tier, issues). It does not differentiate from the sibling faf_score, which likely also produces a score, so an agent cannot fully disambiguate without opening both.

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 after faf_init or when checking if a .faf file meets quality standards" gives a concrete trigger and sequencing. It stops short of stating when NOT to use it or naming an alternative to faf_score, which is the obvious candidate.

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