Server Quality Checklist

Tool Scores

• faf_benchA
  3.5/5.0
  Behavior4/5

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

  Annotations declare readOnlyHint=true and destructiveHint=false, consistent with a non-destructive benchmark. The description adds behavioral context: grading is mechanical (no judge/rubric), and responses are keyed to the .faf. This exceeds the annotations' information.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness2/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is overly poetic and verbose ('Prove the .faf earns its place', 'cold→with-faf lift with a ✪ receipt'), which sacrifices conciseness. Critical information is present but not front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers actions and parameters, but lacks explicit example usage or description of the output format (though output schema exists). The mention of a '✪ receipt' is vague.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with descriptions for all 7 parameters. The description adds workflow context (e.g., 'cold' answers without .faf, 'faf' with it) that clarifies parameter usage beyond the schema. However, some repetition exists.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool measures how much context (the .faf) is worth, distinguishing it from siblings by focusing on falsifiable benchmarking. However, the metaphorical language ('Prove the .faf earns its place', 'cold→with-faf lift with a ✪ receipt') may cause confusion.

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

  Usage Guidelines3/5

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

  It explains the two actions (questions, grade) and when to use each, but does not explicitly state when to avoid this tool in favor of siblings like faf_score or faf_trust. The guidance is adequate but not comprehensive.

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

• faf_contextA
  3.8/5.0
  Behavior1/5

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

  The annotations declare readOnlyHint: true, implying the tool is read-only, but the description claims it can 'set' the path, which is a mutation. This contradiction undermines transparency, as the agent cannot determine the true nature of the operation. The description does not clarify permissions or side effects beyond the contradiction.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, front-loaded with the core action, and includes a clear usage instruction. No unnecessary words or redundant information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description explains the tool's purpose, usage, and what it returns, which is sufficient for a simple setup tool with an output schema. However, the contradiction slightly reduces completeness as the agent cannot fully trust the behavioral description.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  With 100% schema coverage, the baseline is 3. The description adds value by explaining that if path is omitted, the tool shows the current context, which clarifies the optional parameter's behavior beyond the schema description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool sets or shows the active project path, and explains that subsequent faf_ calls resolve against this path. This specific verb+resource combination distinguishes it from sibling tools, which are action-oriented rather than configuration-oriented.

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

  Usage Guidelines4/5

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

  The description explicitly says to call this once at the start of a session so other tools target the right project, providing clear when-to-use guidance. However, it does not mention when not to use it or alternative approaches, though this is less critical given the tool's setup role.

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

• faf_trustA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true, so the description adds value by detailing what the tool does: it returns a receipt containing validity, score, and a deterministic parity hash. This provides behavioral context beyond the annotations, though it doesn't cover potential side effects like session changes.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise (three sentences), front-loads the purpose, and includes key details without extraneous information. Every sentence adds value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  While the description explains the tool's purpose and return value, it omits important context about the path parameter being optional and setting session context for subsequent calls. Given that the output schema exists, the return is covered, but the side effect on session is not mentioned, leaving a gap in completeness.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema covers the single parameter 'path' with a description that already explains it sets session context. The tool description does not add further parameter details. With 100% schema coverage, a baseline of 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool attests a project.faf's integrity, listing specific components (validity, score, parity hash) and uses the verb 'attest', which distinguishes it from sibling tools like faf_score or faf_about. It provides a distinct purpose.

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

  Usage Guidelines4/5

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

  The description includes explicit usage guidance: 'Use this to prove a score is genuine and untampered.' This tells the agent when to apply the tool. It does not explicitly mention when not to use it or name alternatives, but the context implies it's for trust verification, setting it apart from other faf tools.

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

• faf_syncA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior (destructiveHint=false). The description adds important context: 'Updates each block in place — it never overwrites your file', which clarifies the mutation style. 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences front-load the core action and target files, then provide usage guidance. No redundancy or filler. Every sentence adds value.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description explains what the tool does, to which files, and when to use it. There is no output schema, but the tool's output (synced files) is implied. For a simple sync tool, this is sufficient. Could include side effects or prerequisites, but current version is adequate.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% and all parameters have clear boolean descriptions. The description adds minimal extra meaning beyond the schema, listing target files in prose. This meets the baseline for high coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description explicitly states the verb 'Sync', the resource 'project.faf', and the target files (CLAUDE.md plus optional others). It distinguishes the tool from siblings like faf_about or faf_enhance by clearly defining its unique purpose.

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

  Usage Guidelines4/5

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

  The description gives a clear when-to-use instruction ('Use this after editing project.faf') and explains the tool's behavior (updates blocks in place, never overwrites). It implicitly tells when not to use it (for other operations). An explicit alternative would improve it to 5.

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

• faf_initA
  4.3/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=false (write operation) and destructiveHint=false (not destructive). The description adds value by clarifying that it won't overwrite without force and that it returns the file path and starting score, but does not elaborate on other behavioral aspects like permissions or side effects.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences: first states purpose, second gives caveats and alternatives. No unnecessary words, and critical information is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple tool with two optional parameters and no output schema, the description covers purpose, return values, and alternatives. The mismatch between description and schema inputs (name/goal/language) is a minor gap, but overall context is adequate.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, providing descriptions for both parameters (path, force). However, the description mentions 'name, goal, and language' which are not schema parameters, creating confusion about the tool's inputs. It adds little meaningful parameter information beyond what the schema already provides.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses the verb 'Create' and specifies the resource 'project.faf', mentioning that it includes a name, goal, and language. It clearly distinguishes from sibling tools by naming faf_auto and faf_go as alternatives for different tasks.

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

  Usage Guidelines5/5

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

  The description explicitly states that it will not overwrite an existing file and provides specific alternative tools (faf_auto, faf_go) for different use cases, giving clear when-to-use and when-not-to-use guidance.

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

• faf_aboutA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns format metadata and MCP bridges, providing additional behavioral context without contradicting annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, each earning its place. The first states the function, the second gives usage guidance. No unnecessary words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no parameters, no output schema, and simple functionality, the description is complete. It explains what the tool does, what it returns, and when to use it.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters and schema description coverage is 100%. The description does not need to add parameter meaning, and the baseline score of 4 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Explain') and resource ('FAF format'), clearly stating it returns metadata and bridges. It distinguishes from siblings like faf_init and faf_sync, which have different purposes.

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

  Usage Guidelines4/5

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

  The description explicitly says 'Use this when someone asks what FAF is or how it connects to other AI tools.' This provides clear when-to-use guidance, though it lacks explicit when-not-to-use mentions.

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

• faf_autoA
  4.5/5.0
  Behavior4/5

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

  The description reveals return behavior (what was detected and updated score) and the 'no hardcoded defaults' principle. It implies a write operation via 'fill', but does not explicitly state side effects on existing files, though the force parameter partly addresses this. No contradiction 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise, with three clear sentences: action, return value, and usage guidance. It is front-loaded with the primary behavior and avoids unnecessary elaboration.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the simple parameter set and no output schema, the description adequately covers purpose, return value, and usage. It also provides contextual differentiation from siblings, making it sufficiently complete for an AI agent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% for both parameters, so the schema already documents their meaning. The description adds context about scanning manifests, which aligns with the path parameter, but does not substantially enhance parameter understanding beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool scans manifests and fills project.faf stack slots from real dependencies, with specific verbs and resources. It also distinguishes from sibling faf_go by focusing on technical context.

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

  Usage Guidelines5/5

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

  Explicitly says 'Use this for the technical context; use faf_go for the human 6Ws it can't detect,' providing clear usage context and an alternative tool.

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

• faf_doctorA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that the tool reports issues and returns a checklist, confirming it is a read-only diagnostic. No contradictions, and the behavioral description aligns with 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, front-loaded with purpose and output, then usage condition. Every sentence adds value with no wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's diagnostic nature, the description covers what it does, what it returns (checklist), and when to use it. An output schema exists (though not shown in input), so return values are documented elsewhere. No gaps identified.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  There is one parameter 'path' with schema description: 'Project path. Sets session context for subsequent calls.' The tool description does not repeat this, but schema coverage is 100%, so baseline is 3. The added context of setting session context is helpful, raising the score.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'Diagnose a project.faf: report empty or weak slots, common issues, and how to fix each. Returns a prioritized checklist.' This is a specific verb and resource, and it distinguishes from sibling tools like faf_score and faf_about by focusing on diagnosis and actionable fixes.

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

  Usage Guidelines4/5

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

  Explicitly provides a use condition: 'Use this when faf_score is below target and you need to know why.' This helps the agent decide when to invoke. No explicit when-not-to-use is given, but the positive guidance is sufficient.

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

• faf_recallA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds behavioral details: ranking by priority then recency, filtering, and return of matching entries. 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences: first defines function and behavior, second gives usage guidance. No waste, front-loaded with essential information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a retrieval tool with 6 parameters, an output schema, and annotations, the description explains purpose, usage, filtering, sorting, and return type. No need to reiterate output schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description covers 100% of parameters. Description does not add per-parameter details beyond schema, but overall behavior (ranking) is noted. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states it recalls memories from the project soul, ranked by priority and recency, and filters by query/tags/type. Distinguishes from sibling faf_etch by contrasting recall vs. add.

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

  Usage Guidelines5/5

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

  Explicitly says 'Use this to surface past decisions; use faf_etch to add new ones.' Provides direct context and alternative tool, making it easy for the agent to choose.

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

• faf_scoreA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety is clear. The description adds that it uses a 'deterministic Mk4 engine', which is extra 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences: first defines purpose and output, second provides usage guidance. No wasted words, front-loaded with key information.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers purpose, output (with tier and breakdown), usage guidance, and engine detail. Output schema exists, so return values are explained there. Complete for a simple scoring tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100% (both parameters have descriptions). The description does not add any extra meaning beyond what the schema provides, so baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool scores a 'project.faf' and returns '0–100% AI-readability, tier, and per-slot breakdown' using a specific verb 'Score' and resource. It distinguishes from sibling 'faf_doctor' by noting it's for quick checks vs. diagnosis.

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

  Usage Guidelines5/5

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

  Explicitly tells when to use this tool ('quick status check') and when to use an alternative ('use faf_doctor when you need to diagnose and fix'). This provides clear decision guidance.

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

• faf_etchA
  4.8/5.0
  Behavior4/5

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

  Description discloses that it's a write operation (consistent with readOnlyHint=false), returns an ID, and mentions re-etching updates in place (dedup). It also notes that the 'path' parameter sets session context. Annotations already cover non-readonly and non-destructive. Slight additional context could be added about overwriting behavior, but sufficient.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Three sentences: first states action and return, second gives usage guidance, third gives alternative. Every sentence earns its place. No wasted words.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Tool has 6 parameters (1 required), full schema coverage, and output schema exists. Description covers purpose, usage, return value, dedup, and session context. Annotations provide readOnly/destructive info. Complete for agent decision-making.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  With 100% schema coverage, baseline is 3, but description adds significant value: for 'text' it specifies 'capture the why'; for 'id' it explains dedup and update behavior; for 'priority' it explains recall ordering; for 'tags' it provides usage examples and filtering coupling; for 'path' it explains session context. All add meaning beyond schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's action: 'Remember a decision, gotcha, or win across sessions by writing it to the project soul (.fafm).' It also specifies the return value: 'Returns the stored memory's id.' This distinguishes it from sibling faf_recall, which reads memories.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool: 'Use this to persist something an AI should recall later;' and when not to: 'use faf_recall to read them back.' This provides clear guidance and alternative.

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

• faf_goA
  4.8/5.0
  Behavior5/5

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

  Discloses key behaviors: bootstrapping project.faf if missing, asking the 6Ws, returning a Table-of-8, and applying answers. No contradictions with annotations (readOnlyHint=false aligns with create/write operations).

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Concise, front-loaded with a clear metaphor, and every sentence serves a purpose—no redundant or unclear phrasing.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers the overall workflow and interaction pattern, though it does not detail return types (e.g., Table-of-8 structure). Acceptable given tool complexity and missing output schema.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema covers 100% of parameters, and description adds context beyond schema by explaining the flow (e.g., answers field applies keys like 'project.goal'). Adds moderate value.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's role as a setup assistant ('the friendly front door'), describes the verb actions (asks, applies, bootstraps), and explicitly distinguishes itself from sibling faf_auto for the technical stack.

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

  Usage Guidelines5/5

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

  Explicitly states when to use ('from nothing to the 6Ws') and when not to ('use faf_auto for the technical stack on its own'), providing clear alternatives.

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