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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds useful behavioral context: it reads nothing and writes nothing, returns plain text, and includes the server version. This is more than the annotations provide and is clearly stated.

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 core purpose. It is tight but slightly packs three ideas (definition, output, usage) into the first sentence, which is still efficient. Minor room to split, but no wasted words.

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 no-parameter, no-output-schema tool, the description covers what it does, what it returns, and when to use it. With annotations covering read-only behavior, no further context is required.

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 baseline is 4. The description correctly implies no input, and the schema confirms an empty object. No further parameter detail is needed or given.

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 ('Explain') and resource ('.faf format'), then adds concrete scope: what it is, how this server uses it, and that it returns a plain-text overview with server version. This clearly distinguishes it from siblings like faf_score or faf_init, which perform operations.

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 explicit when-to-use guidance: 'Use it when someone asks what FAF is.' It doesn't name alternative tools, but none of the siblings serve this explanatory purpose, so implicit exclusivity is reasonable.

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?

Beyond the annotations, the description explains exact fill rules, that existing values are kept, what happens to typed None/placeholder slots, that changes are listed, that CLAUDE.md's faf-managed block is written, and what the tool returns. This gives strong behavioral context for a destructive 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?

The description is front-loaded with the core action and every sentence carries behavioral detail. It is dense and sentence three is complex, but no content appears purely redundant.

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 supplies the return information: filled values and faf-cli's score before and after. It also covers side effects, slot rules, and the related faf_go boundary, making it 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?

The input schema has one parameter with 100% description coverage, so the schema already documents path and its session-context role. The description adds no further meaning about the path parameter, matching the baseline when schema coverage is high.

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: it creates or fills <folder>/project.faf using repo detection. It also distinguishes its behavior from faf_go by noting that faf_go handles the human 6W questions.

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 clearly indicates context: use it to auto-fill project.faf from repo facts, and defer human 6W input to faf_go. It does not list every alternative sibling such as faf_init or faf_sync, but the primary usage distinction is explicit.

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, idempotentHint, and non-destructive; the description adds real context beyond them - the questions are 'answer-key-safe', grading is mechanical with no judge or rubric, and the result is a cold→with-faf lift with a receipt hash. It also confirms the read-only nature ('Reads only'), consistent 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?

Content is dense and front-loaded: the purpose, the mechanism, and the two-action flow appear in order with no filler. Sentences are long and somewhat jargon-heavy, but each carries 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?

With an output schema present, the description needn't explain return values, and it still covers the two actions, their sequencing, and the meaning of the cold/faf split. An agent has enough to invoke it correctly, with only minor gaps like token-field usage not being explained narratively.

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%, including per-parameter descriptions for faf, cold, action, and token fields, so the schema does the heavy lifting. The description reinforces the cold-vs-faf distinction and the default action but adds little syntactic detail beyond the 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?

The description states a concrete purpose - measuring how much the project.faf context is worth on the current repo via mechanically graded questions - and enumerates both actions (questions, grade). It clearly differs from sibling tools like faf_score or faf_about, though the metaphorical opening ('earns its place') adds flavor before the operational statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear workflow: call action=questions to get the answer-key-safe set, then action=grade with cold and faf answers to obtain the delta. It does not explicitly state when to prefer this over siblings such as faf_score, but the internal usage guidance is concrete.

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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real beyond-annotation context: the refusal of home folder and filesystem root, the fact that path redefines the context used by all other pathless faf_* calls, and 'Writes no file.' It is slightly redundant on the read-only point.

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 dense sentence-pair, front-loaded with the purpose and followed by parameter behavior and session guidance. Every clause 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?

With an output schema present, return values need no explanation. The description covers purpose, both parameters, the state effect on sibling calls, refusal conditions, and session timing — complete for a simple 0-required-param context 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%, so baseline is 3, but the description adds meaning beyond the schema: path re-points the active project and has documented rejection cases, and detail:true surfaces the .faf text. These behavioral consequences go beyond the terse 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?

States a specific verb (show) and resource (the active project folder and its .faf), and clarifies the concept precisely: it is the folder every faf_* call without a path uses. This distinguishes it from siblings like faf_init or faf_about without needing schemas.

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 call it ('once at the start of a session') and when to pass path (to switch projects). It does not name an alternative sibling or state when-not-to-use, but the session-start guidance and the concept of the shared context are clear.

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, idempotentHint, and destructiveHint=false, and the description's 'Reads only' merely restates that. It does add that the output is a checklist of findings each paired with a fix, which is mild extra context. With an output schema present and safety already covered, no deeper disclosure is required, but little is added beyond structured data.

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 verb+resource, and the closing usage rule is short and actionable. The first sentence is a run-on packing several checks and two sibling names into one breath, which costs a little readability but there is 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?

Covers what is diagnosed, the read-only nature, and the trigger condition, and an output schema exists so return values need not be described. For a single-optional-parameter diagnostic tool this is close to complete, missing only explicit exclusions or a follow-up path.

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 optional parameter whose schema description is 100% covered ('Project path. Sets session context for subsequent calls.'). The description adds no further meaning about the path argument, so the schema carries the load and baseline 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 verb and resource ('Diagnose the project's .faf') and enumerates the checks performed: validateFaf errors, score/empty slots, CLAUDE.md presence, formats found. It also names the siblings that supply fixes (faf_auto, faf_go), so it is distinguishable. The dense parenthetical phrasing keeps it just 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?

Gives an explicit trigger condition: 'Use it when faf_score is below 100%', which routes the agent from a sibling tool to this one. It does not state when not to use it or what to do after diagnosis, but the primary selection condition is unambiguous.

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?

Goes beyond the annotations by disclosing the write target (soul.fafm), the dedup/update-in-place semantics of re-etching an id, and the return payload. It does not warn about the destructiveHint=true aspect beyond noting in-place overwrite, and no permission or auth prerequisites are mentioned.

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 mutation/dedup rule, then the usage pointer to the alternative. No filler and nothing buried.

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 6-parameter mutation tool with full schema coverage, output schema present, and annotations already declaring the safety profile, the description covers purpose, persistence target, dedup behavior, and the sibling relationship. Nothing an agent needs 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 every parameter is already documented in the schema (id dedup, path session context, tags, priority ranking). The description adds no per-parameter meaning beyond that, which is the expected baseline 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 (etch/remember) and resource (a memory written to soul.fafm), plus the storage mechanism (faf-cli's Soul). It is clearly distinguishable from sibling faf_recall, whose role 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?

Gives a clear when: 'Use it to persist something an AI should recall later', and names the complementary reader faf_recall. It does not state any when-not conditions (e.g. don't etch ephemeral scratch state), so it stops short of full 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so safety is covered structurally. The description adds real value beyond that: answers are written in place, an answered slot's existing value is replaced, invalid keys or non-text answers are refused with nothing written, and project.faf is created via faf_init/faf_auto if missing. That is meaningful side-effect disclosure for a mutating 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?

Two long, densely nested sentences pack in every behavior but bury the critical read-vs-write fork mid-clause, so it is not front-loaded for quick scanning. The information is mostly load-bearing, but nested asides ('faf_auto writes it: its dry run, the one faf_formats shows') hurt parseability.

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 return-value burden, and it does state the return (the Table-of-8 plus score in read mode, the new score in write mode). It also covers creation side effects and refusal behavior. What is missing is any guidance on subsequent calls or the session-context effect of path beyond the schema note.

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 both parameters are documented in the schema, so the baseline is 3. The description restates the slot-path→text answer shape and the refusal rule, but adds little syntax or format detail the schema does not already supply (its example values overlap the schema's own examples).

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 defines a specific dual-mode tool: read-only interview output (the Table-of-8 seeded from the goal with score) when no answers are given, and an in-place writer of answers into <folder>/project.faf when they are. It positions itself against siblings by naming faf_auto and faf_init as things it invokes and faf_formats as showing the dry run. However, jargon like 'Table-of-8' and 'the human half of project.faf' assumes familiarity, so an unfamiliar agent needs more parsing than ideal.

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 implicitly delineates when each mode applies (no answers = inspect, answers = write) and names the parent workflow (faf_init/faf_auto run first if project.faf is absent). But there is no explicit 'use this instead of X' routing or stated prerequisites beyond that, so the agent must infer when faf_go beats faf_auto or faf_score.

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 flag destructive=true, but the description adds material context beyond them: an existing file is left untouched by default, and force:true copies the old file to a project.faf.bak-<time> backup before replacing. It also discloses what the reply contains (path, starting score, .faf-dna), which carries weight since no output schema 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 core action and keeps to three dense sentences with no filler. Slightly heavy with multiple clauses, but every sentence carries useful 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?

For a destructive, zero-required-param create tool with no output schema, the description covers invocation outcome (returned values), default safety behavior, the force override, and alternatives. An agent has everything needed 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 both parameters are already richly documented in the schema. The description restates force's replace-and-backup behavior but adds no syntax or resolution detail beyond what the schema provides. 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?

States a specific verb ('Create') plus the exact resource ('project.faf') and adds the detection behavior (name, language, stack) that defines the tool. It explicitly differentiates itself from siblings faf_auto and faf_go, so an agent can disambiguate 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?

Clearly states when to use it (creating a new project.faf) and, crucially, what to do instead when a file already exists — route to faf_auto for filling empty slots or faf_go for human 6Ws. Even names the force condition and its consequence.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so 'Reads only' is largely redundant. However, the description adds real behavioral context beyond the annotations: the backing store (soul.fafm), the deterministic ranking order (priority then recency), and the fact that filtering is conjunctive across query/tags/type.

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 scope, then filters, then the routing hint to faf_etch. No filler; every clause carries 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?

With an output schema present, the description need not explain return shape, and the one-line 'Returns the matching entries' is sufficient. For a six-parameter read tool it covers filters, ordering, and the sibling write path, though it omits default limit behavior and any note on empty results.

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 all six parameters, including the query substring semantics and the minPriority default. The description only restates the filter dimensions and adds result ordering (priority then recency), which is genuinely extra but marginal against a fully documented schema. Baseline 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 verb and resource ('Recall memories from the project soul (soul.fafm)') and immediately specifies the retrieval model ('ranked by priority then recency, filtered by query/tags/type'). It explicitly names the sibling it is not ('faf_etch adds new ones'), so an agent can route between the read and write tools 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?

Gives a concrete use case ('surface past decisions') and names the complementary alternative, faf_etch, with its contrasting behavior. It stops short of stating when NOT to use it (e.g. when to prefer faf_context or a live search over stored memories), so it is clear context without explicit exclusions.

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 readOnly, idempotent and non-destructive, so the bar is lower; the description reinforces this with 'Reads only' and goes further by disclosing the exact output composition (score, tier, slot states, faf-parity/v1 hash). It does not mention failure modes or cost, but adds real context 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 core action and output are front-loaded and the total length is appropriate. The dash-heavy, list-like styling and the aside 'the one score every faf tool reports' add flavor but slightly dilute an otherwise tight definition.

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, yet the description still summarizes them usefully. With only two optional parameters, full schema coverage, and clear safety annotations, an agent has everything needed to invoke this 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 both parameters are already documented in the schema, which establishes the baseline of 3. The description's note that details:true lists every slot as populated/empty/slotignored largely restates the schema, adding little new syntax or edge-case meaning.

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 the project's .faf with faf-cli's scorer') and enumerates exactly what the score contains (0–100%, tier, slots, parity hash). It also names faf_doctor as the sibling for remediation, so an agent can distinguish it from the other faf_* 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?

It gives clear context ('Reads only') and routes the agent to faf_doctor 'for what to fix', which is an explicit alternative. It stops short of stating when scoring itself is the right call versus e.g. faf_bench or faf_trust.

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 adds substantial behavioral detail beyond the annotations: it previews before writing, requires confirm: true to mutate, modifies only its own hook entry, preserves every other key and hook, and refuses the user settings/home folder. These details clarify the safety envelope and mutation semantics, consistent with readOnlyHint=false, destructiveHint=false, and idempotentHint=true.

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 compact and front-loads the main action before its conditions. It packs a lot into one long compound sentence, which is efficient but slightly dense. Every clause earns its place by covering install, preview, confirm, scope, and removal.

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 three-parameter hook-management tool with a full output schema, the description covers the critical operational facts: default preview, confirm-gated write, removal behavior, scope of changes, and refusal of user settings. An agent has enough context to invoke it correctly without needing return-value details.

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 are already documented in the input schema. The description reinforces confirm and remove semantics, but does not add parameter syntax or formats beyond what the schema provides. A baseline score of 3 is appropriate when the schema carries the parameter-documentation burden.

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: install the native SessionStart hook in the project settings. It also explains the downstream effect, that every Claude Code session starts with fresh .faf context, and covers both install and remove modes. This distinguishes it from sibling tools like faf_init or faf_context, which manage context rather than session-hook installation.

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 gives clear operating context: preview is the default, writes happen only with confirm: true, and remove: true targets only the faf hook. It also states an explicit exclusion, that user settings and the home folder are never written. However, it does not name or compare against alternative faf tools for related setup tasks.

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 and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: each target file preserves all lines outside faf's block, and failures are returned per-file with a reason plus isError. It does not say whether concurrent writes are safe, but the merge semantics are a meaningful addition.

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 purpose is front-loaded, but the text is one long run-on with redundant jargon — "faf-cli's render and injector" and "with faf-cli's writers" say the same thing twice and cost the reader without adding information. It is functional but not tight.

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 documentation is not strictly required, yet the description usefully frames the write results and failure reporting. With 6 optional params all documented in the schema, and file-preservation semantics stated, an agent has enough to invoke it correctly; only the sibling distinction 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 the baseline is 3. The description restates the flag-to-file mapping (agents, cursor, gemini, copilot, all) that the schema already documents, adding no syntax, precedence (e.g. all vs a single flag), or default behavior 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 — writing project.faf into CLAUDE.md as a faf-managed block, optionally into four other files. It is clear what the tool does, but it never distinguishes itself from the sibling faf_tri_sync, which is the nearest potential overlap, so an agent cannot rule that one out from the text alone.

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 it after editing project.faf" gives a concrete trigger condition that tells the agent when this tool is appropriate. It provides no when-not guidance and does not name alternatives among the 13 siblings, so it stops short of full routing guidance but is more than implied usage.

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 annotations covering safety (idempotent, non-destructive), the description adds real behavioral value: it localizes the target path, CLAUDE_CONFIG_DIR override, and — crucially — specifies that only the managed block changes, all of Claude's notes are preserved, and the reply is asserted only after reading the file back. That verification and preservation guarantee goes well beyond what readOnlyHint/destructiveHint convey.

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, no filler, front-loaded with the primary action and target before the readback guarantee and sibling routing. Every sentence earns its place, including the path and config-dir override.

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?

No output schema exists, yet the description tells the agent what the reply means ('the reply says so only after reading the file back') and what is and isn't modified. For a 2-param write tool with no return schema, this is complete enough to invoke 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 both parameters are already documented. The description repeats the 'status reads only' and default-export semantics that the schema's enum description already carries, adding no syntax or edge-case detail. Baseline 3 is correct.

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?

Names a specific verb and resource ('Write project.faf as a faf-managed block into the MEMORY.md'), states the exact target file and its location, and explicitly distinguishes itself from the sibling faf_sync ('faf_sync writes CLAUDE.md'). An agent can pick between the two 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?

It routes the agent to an alternative (faf_sync for CLAUDE.md) and disambiguates the 'status' mode as reads-only. It does not spell out prerequisites or when-not-to-use beyond the sibling contrast, so it stops short of the top band.

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, idempotentHint, non-destructive, closed-world. The description adds the important failure behavior: invalid .faf or unknown score yields isError/no receipt; 'Reads only' is redundant but consistent. It stops short of permission/rate-limit context.

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 verb and core behavior, then return and error condition; no bloated preamble. The final 'Reads only' is redundant against annotations, keeping it from a perfect score.

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?

Output schema exists and annotations cover safety, so return values and read-only nature need not be fully explained here. The description does cover the receipt and error case, making it sufficiently complete for this read-only attestation 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?

Single path parameter has 100% schema description coverage, so the schema already explains its role. The description adds no further syntax/default/context for path, so baseline 3.

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 ('Attest') and resource (the project's .faf) and enumerates the composite checks (validateFaf, score, parity hash) and returned receipt. This is clearly not a bare score tool, but it does not name a sibling alternative to route among faf_score/faf_doctor.

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 when-to-use guidance, prerequisites, or alternatives to sibling tools are provided. Usage is only implied by the attestation purpose, so an agent gets little help choosing this over faf_score or faf_doctor.

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