.FAF Context

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

Annotations already declare readOnlyHint=true, and the description adds that it returns a plain-language overview. No side effects or additional behaviors need disclosure; description aligns with 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 sentences, no wasted words. First sentence explains the format, second explains usage. Front-loaded and efficient.

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, simple informational tool, the description fully covers purpose, format, and usage context. No gaps given the low complexity.

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?

No parameters, so schema coverage is 100%. Baseline is 4; description need not add parameter info.

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?

Description clearly states the tool explains the .faf format, its IANA registration, and purpose. It distinguishes from sibling tools by specifying it is for understanding the concept before using other 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?

Explicitly says 'Use this when you or the user are new to FAF and want the concept before running other tools,' providing clear guidance on when to use. Does not list when not to use, but this is a simple informational tool so not necessary.

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, and openWorldHint=false, so the write-but-safe profile is covered structurally. The description adds only that it "Returns the merged or written result for the chosen action"; the richer behavioral caveats (force preserves content outside the managed block, merge controls whether anything is written) live entirely in the schema, not the description.

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 sentences, front-loaded with the bidirectional purpose and ending with the use case. The middle sentence about return values is mildly redundant but earns its place by signaling the action-dependent output. 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?

For a sync tool with no output schema, the description covers the two directions of flow, the action-dependent return, and the motivating use case. Annotations carry the safety profile and the schema carries parameter detail, so the remaining gap is minor.

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 100%, and the schema thoroughly documents action, merge, force, and path, including enum semantics. The description adds no parameter-level meaning beyond that, so the baseline 3 is appropriate.

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 specific verbs and resources: importing AGENTS.md into project.faf and writing AGENTS.md from project.faf. The naming of the OpenAI/Codex convention implicitly distinguishes it from sibling convention tools (faf_claude, faf_cursor, faf_gemini), but it never names or contrasts them 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 states the use case clearly: "Use this to keep a Codex/OpenAI-style AGENTS.md and your .faf in agreement from one source." That gives a clear context for when to reach for it, but there are no exclusions or named alternatives (e.g., when to prefer faf_claude or faf_sync instead).

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 and openWorldHint=false, so the write/scope profile is covered. The description usefully adds what the tool creates (project.faf and CLAUDE.md) and that it returns the final AI-readiness score. It does not say whether existing files are overwritten versus merged, or how the 'init or merge' branch is chosen — meaningful gaps for a mutating orchestrator.

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 action sentence, then return value, then routing guidance — a sound order. The pipeline enumeration clause is dense with em-dashes and parentheses but each sentence carries distinct information, 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?

With no output schema, the description compensates by stating the return ('final AI-readiness score and what was created') and the artifacts produced. It is nearly complete for an orchestration tool; only the init-vs-merge decision rule and overwrite behavior for existing files are missing.

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 100% for the single 'path' parameter, and the schema documents its session-context side effect. The description adds nothing about the parameter, so the baseline of 3 applies for a fully documented one-param tool.

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?

Specific verb and resource ('run the setup pipeline in one call') with an explicit enumeration of the stages it chains (init/merge, stack detection, CLAUDE.md, score). It also names the sibling it complements (faf_go) and the alternative class (the individual tools), so an agent can place it without opening any 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?

Explicit routing: 'Use this as the fast path on a fresh project; use the individual tools when you need finer control.' It states both the condition that selects this tool and the condition that selects alternatives, plus where faf_go fits after it.

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 only give the generic readOnlyHint=false/destructiveHint=false profile, while the description adds the genuinely useful disclosure that _protected_fields is advisory and NOT enforced by other tools, plus that unlock clears the list. That is real behavioral context beyond structured fields. It stops short of stating persistence or the shape of the returned ratings.

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 sentences, front-loaded with the core operation and no filler; the protect/unlock clauses are appended efficiently. The semicolon-chained middle sentence is slightly dense 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?

With no output schema and only three simple parameters, the description covers the operation, the two mutating flags, and the advisory caveat. An agent has enough to call it correctly; only return-format details are absent, which is a minor gap for a tool that returns ratings.

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 100%, so all three parameters (path, protect, unlock) are already documented in the schema, and the description's explanation of protect/unlock largely restates the schema wording. Baseline 3 is appropriate since the schema does the heavy lifting.

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 verb (inspect), a specific resource (human_context fields), and the operation performed (rate each empty/generic/good). It is clear what the tool does, though it never contrasts itself with the adjacent faf_score or faf_context siblings, so an agent must infer the boundary.

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 gauge context quality" implies the intent but gives no when-to-use vs. when-not guidance and never names an alternative (e.g. faf_score). The protect/unlock conditions are described, but that is parameter behavior rather than tool-selection 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutation is expected and the safety profile is partially covered. The description adds real value beyond that: it discloses the faf-managed block boundary and that surrounding content is preserved during the write, and it states the return payload ('the files written'). It does not describe overwrite behavior when no managed block exists.

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-loads the primary output and direction before the optional-format detail, and the parenthetical legacy-name note is compact. The middle clause about preserved content is load-bearing rather than filler, though the sentence runs long with several parentheticals.

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-required-parameter write tool with no output schema, the description covers what is written, where the write is bounded, that files are reported back, and how to expand the output set. The main remaining gap is precedence among the flags and 'all', which the schema hints at but never resolves.

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 100%, so every parameter including 'all' and the per-format booleans is already self-documenting; baseline is 3. The description references the format flags and 'all' but adds no syntax, interaction rules, or precedence detail beyond what the schema already conveys.

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 ('Write CLAUDE.md from project.faf') and pins the direction of the operation with '.faf → CLAUDE.md', which is genuinely distinguishing detail. It also enumerates the additional artifacts the format flags produce. It stops short of differentiating itself from the near-identically named siblings faf_agents, faf_cursor, and faf_gemini, which an agent would reasonably confuse with the flag-driven behavior here.

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 a clear motivating context ('Use this to keep every AI tool's context file current from one source') and implies the flag-based fan-out path, plus a rename note for older callers. It never states when NOT to use this tool or when to prefer the individual faf_agents/faf_cursor/faf_gemini siblings over the flags.

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?

The description notably discloses that when invoked with a path it mutates session state that other tools resolve against, and that omission returns the current path. However, annotations declare readOnlyHint=true, which conflicts with an operation whose 'Set' branch changes the resolution context for every subsequent project tool call — a side effect on the environment. The description is honest, but the structured safety signal is misleading, so this is flagged as a contradiction.

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: the core purpose and resolution semantics come first, the return value second, and the session-start directive last. The parenthetical about faf_read/faf_write earns its space by preventing a likely misuse. 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?

For a one-optional-parameter tool with no output schema, the description covers purpose, the read/write duality, the returned value, and the recommended call timing. An agent has everything needed to invoke it correctly; only the annotation mismatch mars the picture.

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 the single parameter's description already states 'Set active project path. If omitted, shows current context.' The prose restates that behavior with no added syntax, format, or validation detail, so the baseline 3 is appropriate when the schema carries the load.

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 set (set/show) on a specific resource (the active project path) and explains its downstream effect on 'later faf_ project tools.' It even differentiates itself from sibling behavior by noting that faf_read and faf_write resolve against the server's working directory instead. An agent can distinguish this from faf_init or faf_sync 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 explicit timing guidance: 'Call this once at the start of a session so the project tools target the right project,' and clarifies which tools it does and does not affect. It lacks an explicit when-not-to-use case (e.g., what happens if you call it twice, or whether it is required before faf_read/faf_write), so it falls 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 declare this is a write operation (readOnlyHint=false) that is neither destructive nor open-world, so the safety profile is already covered. The description adds that it returns the merged or written result, useful given there is no output schema, but it does not disclose the write-over-file nuances that the schema's merge/force params imply.

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 minimal waste: the operation, the return, and the intent. It is appropriately sized, though the middle sentence about return values is partly redundant with the action description.

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 moderate-complexity mutation tool with full schema coverage and annotation-backed safety, the description covers the what, the return, and the purpose. Nothing beyond minor sibling disambiguation is missing to call 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?

Schema description coverage is 100%, so all four parameters are fully documented in the schema, including the action enum and the merge/force semantics. The description mentions only the import/export direction and adds no meaning beyond the schema, so the baseline of 3 applies.

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 bidirectional resource operation: importing .cursorrules into project.faf and writing it back out. The Cursor IDE convention is named explicitly, making the resource identifiable. However, it never distinguishes itself from the sibling tool faf_sync or the analogous faf_claude/faf_gemini conventions, which an agent must disambiguate 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?

The closing sentence ('Use this to keep Cursor rules and your .faf in agreement from one source') gives an implied purpose but no when-to-use versus when-not, and no routing to alternatives. With faf_sync and other convention-specific siblings present, the lack of explicit differentiation leaves selection partly 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further by disclosing the shape of the result ('Returns a checklist') and that each finding carries a fix, which helps an agent interpret output without a schema.

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 sentences, front-loaded with the action and the report contents, followed by the trigger condition. No filler or restatement of the tool 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?

With no output schema, the description carries the burden of explaining the return shape, and it does so (a checklist of issues with fixes). Missing only minor detail about ordering or scope relative to the optional 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?

There is a single parameter ('path') and schema description coverage is 100%, so the schema already explains it fully, including that it sets session context. The description adds no parameter-level meaning beyond that, which is the expected baseline.

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 (Diagnose) and resource (a project.faf setup) and enumerates what the report contains: missing files, the real score with slot counts, and config issues with fixes. It implicitly separates itself from faf_score by promising the 'why' behind a low score, though it never names that sibling 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 states a clear trigger condition: 'Use this when your score is low and you need to know why.' That is real routing guidance, but it stops short of naming the alternative tools (e.g. faf_score for the number alone) or stating when not to use it.

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 this is a non-read-only, non-destructive, closed-world operation, so the safety profile is carried structurally. The description adds that it returns the merged or written result and that data flows both directions, but it does not disclose the practical consequence that sync/force rewrites GEMINI.md or that import alone writes nothing – that caveat lives only in the schema.

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 compact sentences that front-load the operation and follow with the return behavior and purpose. The phrase 'for the chosen action' is mildly redundant given the enum, but overall it wastes little.

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 four-parameter tool with no output schema and full annotation coverage, the description supplies the essential what, why, and return shape. The action-specific write/merge semantics that an agent would need are delegated to the schema, leaving only minor gaps.

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 100% and the action enum values are individually documented in the schema, so the description need not restate them. It adds only the bilateral import/write framing, not meaning beyond what the schema already provides, so the baseline 3 is appropriate.

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 (GEMINI.md, project.faf) and a clear bidirectional verb (import into / write from), with the parenthetical clarifying the Gemini CLI convention. This is easily distinguished from faf_claude and faf_cursor by naming the exact artifact, though it never explicitly contrasts itself with those siblings.

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 closing sentence gives a clear purpose statement ('keep a Gemini context file and your .faf in agreement from one source'), which implies when to reach for it. It stops short of naming alternatives or stating when-not to use it, so it lands just below the explicit routing bar.

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, openWorldHint=true, and destructiveHint=true. The description adds useful scope by saying it fetches a public repo and returns an authored .faf, but it does not explain the write/overwrite behavior, refusal semantics, auth needs, or rate limits beyond what the annotations and schema already imply.

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 compact sentences/clauses, front-loaded with the action and source, then the return value, then the usage context. No filler material.

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 appropriately says it returns the authored .faf. It leaves the optional path-writing and force-overwrite behavior to the schema, which is acceptable because those parameters are fully described there and the annotations signal destructiveness.

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 100%, so the schema already documents url, path, and force in detail. The description mentions the GitHub URL source and the returned artifact but does not add syntax, formatting, or behavioral meaning beyond what the schema provides.

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 ('Author a project.faf') and a specific source ('from any public GitHub repository URL'), then clarifies the extraction behavior. The final sentence distinguishes the use case from local-clone workflows, so an agent can tell what this tool is for 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?

Explicitly says when to use it: to bootstrap context for a project with a known URL but no local clone. It gives clear context but does not name or rule out specific sibling alternatives such as faf_init or local workflow tools.

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?

Despite minimal annotations (only readOnlyHint false, destructiveHint false), the description adds behavioral context: it returns questions, applies answers, updates the score, and implies interactive iteration. It does not detail side effects or error conditions, but adequately describes the interactive protocol.

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 sentences, zero wasted words, front-loaded with the purpose and then details. Every sentence provides critical 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?

Given the tool's complexity (2 params, nested objects, no output schema), the description fully covers what the tool does, when to use it, how parameters behave, and what it returns (next questions and updated score). No missing critical information.

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%, but the description adds notable value: explains path sets session context for subsequent calls, and answers describes the key-value format and the effect of applying answers (new score returned). This goes beyond the 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?

Clearly states the tool drives a project.faf to 100% through a guided interview, returning questions and applying answers. This specific verb+resource+process distinguishes it from siblings like faf_auto (auto-detection) and faf_score (just scoring).

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 to use this tool when auto-detection cannot fill human slots, providing a clear when-to-use and when-not-to-use context. This directly guides the agent to choose this over alternatives like faf_auto.

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 indicate readOnlyHint=false and destructiveHint=false, so the description is not required to restate these. It adds value by explaining the side effect (creating a file) and the return values (file location and starting score). However, it does not mention behavior when the file already exists without the 'force' parameter.

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 relatively concise (three sentences) and front-loads the main purpose. Each sentence provides relevant information, though space could be saved by merging the last two sentences. Overall, it is appropriately sized.

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?

Given the tool's low complexity (2 optional parameters, no output schema), the description covers the essential aspects: purpose, return values, and parameter usage. It does not mention error handling or edge cases, but these are minor gaps for such a simple 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 100%, but the description adds significant semantic detail beyond the schema, especially for the 'path' parameter (smart resolution rules, examples). For 'force', the description is sufficient. The added context helps the agent understand parameter behavior better than the schema alone.

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 the tool creates a 'project.faf' file for a project, making it AI-readable. The verb 'Create' is specific to the resource, and the description differentiates from sibling tools like 'faf_score' or 'faf_sync' by focusing on initialization.

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 clear guidance on when to use the tool: to create a project.faf. It explains acceptable inputs (path, bare name, omit) with examples, but does not explicitly mention when not to use it or suggest alternatives, leaving some ambiguity.

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?

Description aligns with readOnlyHint annotation and adds details on return structure (percentage, tier, optional slot-by-slot breakdown with suggestions). No contradictions.

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 concise sentences, front-loaded with action and output, each sentence serves a clear purpose.

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?

Schema is fully covered, no output schema needed as description explains return object, readOnlyHint covers safety, and all aspects (purpose, usage, parameters, output) are addressed.

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%, description adds value by explaining 'details' as providing 'slot-by-slot breakdown with improvement suggestions' and 'path' as setting session context.

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?

Description clearly states verb 'calculate', resource 'AI-readiness score', and scope. Distinguishes from siblings like faf_context and faf_check.

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 to measure how complete the AI context is and what to fill next', providing clear when-to-use guidance. Lacks explicit exclusions but purpose sufficiently contrasts alternatives.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is partly covered; the description adds the non-obvious trait that this mutating tool is dry-run by default and only writes when apply:true is passed, plus a hard scope boundary on which files it never modifies. It stops short of covering idempotency or conflict handling, so it adds value without being exhaustive.

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: purpose first, then the default/write semantics, then the exclusion boundary. No filler, and the most decision-relevant fact (dry-run by default) appears early.

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 two-parameter tool with no output schema, the description still tells the agent what the dry-run returns ('reports the fields that would change'), what gets written, and what is out of scope. Nothing needed to invoke it correctly is missing.

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 100%, so both parameters are already documented in the schema and the baseline is 3. The description restates the apply semantics (default dry-run vs. write) consistently with the schema but adds no new syntax or edge-case meaning beyond it.

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 ('Reconcile project.faf') plus the authoritative source ('what the repo manifests say now'), listing the concrete inputs (package.json name, description, framework dependencies). It also distinguishes itself from faf_claude and the other file-targeted siblings, so an agent can pick 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 states the default behavior (dry-run reporting) and the opt-in write path (apply:true), and names the correct alternative for a different file set ('Does not touch CLAUDE.md — use faf_claude for CLAUDE.md, AGENTS.md, .cursorrules and GEMINI.md'). Both the when and the when-not are spelled out.

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 context: the exact fields validated and that it invokes faf-cli's validator to produce a "real score," which hints at behavior beyond a simple read. It doesn't describe failure modes or what happens when validation fails.

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?

A single, front-loaded sentence with no filler. The verb and target come first, and the secondary outcome (score report) closes the sentence efficiently.

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 and no params, the description carries the full burden of explaining results. It mentions a score but not the validation report shape (e.g. pass/fail per field), and it doesn't clarify the target file location or how this differs from faf_score, leaving an agent with moderate gaps.

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 no parameters, so there is nothing to document; baseline is 4. The description correctly implies no inputs are needed beyond the implicit project.faf target.

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 ("Validate") and resource ("project.faf's required fields (faf_version, project.name) and about.* block"), and adds that it reports a score. However, it does not distinguish this from close siblings like faf_score or faf_check, which likely also validate or score a project.faf.

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?

No guidance on when to use this versus faf_score, faf_check, or faf_doctor. It doesn't state prerequisites (e.g. that a project.faf must exist) or exclusions, leaving the agent to infer the boundary among several overlapping sibling tools.

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