faf-mcp

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?

The description notes the tool returns a merged or written result, adding context beyond annotations. However, it does not clarify side effects like file modification or potential data loss, which is slightly lacking given destructiveHint=false.

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 concise (two sentences, ~40 words), front-loaded with the key actions and resources, with no redundant 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 no output schema, the description explains the return value (merged or written result). It covers the tool's purpose and the four parameters are fully described in the schema. It is sufficient but could be slightly more explicit about the direction of each action.

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 100% description coverage, so the schema already documents all parameters thoroughly. The tool description adds no additional parameter meaning 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 explicitly states the tool imports, exports, or syncs context between AGENTS.md and project.faf, with a specific verb and resources. It distinguishes from sibling tools by naming the exact files involved.

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 when to use the tool ('to keep a Codex/OpenAI-style AGENTS.md and your .faf in agreement'), but does not explicitly mention when not to use it or suggest 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?

The description discloses that the tool returns the final AI-readiness score and what was created, and implies file creation/modification. However, it does not elaborate on potential side effects like overwriting or whether the tool is idempotent. The annotations (destructiveHint=false) align with the description's non-deletive nature, but a bit more nuance would be helpful.

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 two sentences: the first succinctly states the tool's action and return, the second provides usage guidance. No extraneous information, perfectly front-loaded, and every sentence adds value.

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 (composite of multiple steps), the description adequately covers its purpose, return value, and use case. The simple schema (2 params, no output schema) does not require extensive detail. However, it could hint at internal steps or side effects for completeness.

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 does not add additional meaning to the parameters ('path' and 'force') beyond what is already in the schema. It mentions the overall pipeline but does not explain how parameters affect the pipeline.

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

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

The description clearly states the tool runs the full setup pipeline (init, stack detection, sync, bi-sync, score) and transforms a project from no context to complete. It distinguishes itself from sibling tools by noting that individual tools provide finer control, making its composite nature explicit.

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 directly says 'Use this as the fast path on a fresh project; use the individual tools when you need finer control.' This explicitly defines when to use the tool (fast path on fresh project) and when not to (when finer control is needed), providing clear conditional 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?

Description mentions returns 'formats written and any conflicts,' implying mutation and conflict detection. Annotations show readOnlyHint=false and destructiveHint=false, which align. However, does not disclose if files are created or overwritten, or any side effects beyond what annotations already 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?

Two sentences front-load purpose and usage. No superfluous information. Efficient and clear.

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?

Description explains target files and return value but omits details like what project.faf is, whether files must exist, or how bi-directional sync behaves in conflict scenarios. No output schema to compensate. Adequate but leaves 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 covers 100% of 8 parameters with descriptions. Description adds minimal value by grouping flags as 'format flags or all' and mentioning they sync additional files. 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?

Description clearly states bi-directional sync between project.faf and multiple AI context files (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md). Uses specific verb and resource. However, does not distinguish from sibling faf_sync, which may overlap in functionality.

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 keep every AI tool context file aligned from the single .faf source.' Provides use case but no when-not-to-use or alternatives. No prerequisites or context for when to use other sibling tools like faf_init or faf_check.

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 provide no behavioral hints (readOnlyHint=false, destructiveHint=false). The description adds that protect locks fields and unlock releases them, which are useful behavioral traits. However, it doesn't mention if locks are persistent or rated values are temporary.

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 consists of two compact sentences with the main action first, followed by usage guidance. Every sentence adds value, no redundancy.

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

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

The tool has 3 simple parameters and no output schema. The description explains purpose, parameter effects, and usage context. Lacks details on return format, but for a check tool it is sufficient.

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% with descriptions for all 3 parameters. The description adds meaning: 'with protect it locks good/excellent fields from being overwritten, with unlock it releases them,' which clarifies the effect of the boolean parameters beyond the schema text.

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

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

The description clearly states that the tool inspects 'human_context fields' and rates them, with specific verb 'Inspect' and resource. It distinguishes from siblings like faf_context and faf_score by focusing on rating and protecting fields.

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 says 'Use this to gauge context quality and guard your best answers,' providing clear context for use. It does not explicitly mention when not to use or alternatives, but the purpose is unique enough among siblings.

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

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

Description claims ability to set path (mutation) while annotation readOnlyHint: true indicates read-only. This is a direct contradiction. Additionally, description fails to resolve this inconsistency.

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. First sentence states action and return value. Second sentence provides usage context. 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 simple tool with one optional parameter, the description covers the dual behavior (set/show) and recommends when to call. Missing output schema but return value is mentioned. However, the contradiction with annotations undermines completeness.

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 its description matches the tool description. The description adds no new information beyond the schema's field description. 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?

Description explicitly states the verb and resource: 'set or show the active project path'. It distinguishes from sibling tools by specifying that it resolves for later faf_ calls.

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 advises calling once at session start to target the right project. Implicitly suggests when not to call (when context is already set). No explicit exclusions but sufficient 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 (readOnlyHint=false, destructiveHint=false) indicate modifications but not destruction. Description adds that it returns the merged or written result, providing some behavioral context. However, it does not detail side effects or edge cases (e.g., what happens on conflict).

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 that front-load the main purpose and provide usage guidance. No unnecessary 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?

Given the tool's limited scope (sync between two file types) and the presence of schema with full parameter descriptions and annotations, the description adequately explains the tool's function and expected output. Lacks specifics on result format but is sufficient.

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 parameters. The description adds general context about actions (import/export/sync) but does not add significant meaning 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?

Description clearly states the tool imports, exports, or syncs context between .cursorrules and project.faf. The verb 'sync' and resources are specific, and it distinguishes itself from sibling tools like faf_sync and faf_context by focusing on Cursor rules.

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?

Description provides usage context: 'Use this to keep Cursor rules and your .faf in agreement from one source.' It implies when to use but does not explicitly mention when not to use or provide alternatives. However, the context is clear enough.

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 adds specific details about the types of issues reported (missing files, slots, config issues) and that it returns a fix. Annotations declare readOnlyHint=true, so no contradiction; description enriches the read-only behavior.

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

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

Two concise sentences: first explains function, second provides usage guidance. No redundant or filler content.

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 diagnostic tool with no output schema, description adequately explains return value (prioritized checklist) and types of issues. Complete for agent invocation.

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

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

Only one parameter 'path' with schema coverage 100%. Schema already describes it as 'Project path. Sets session context.' Tool description does not add further semantics beyond implying it is the project to diagnose.

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 diagnoses a project.faf setup, reports specific issues (missing files, empty/weak slots, config issues), and returns a prioritized checklist. Distinct from sibling tools like faf_check or faf_score.

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

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

Explicitly says when to use: 'when your score is low and you need to know why.' Provides clear context but no mention of when not to use or 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 are minimal (readOnlyHint=false, destructiveHint=false). The description adds that the tool 'returns the merged or written result' and implies file modification. It does not detail permissions, side effects, or error scenarios, but the addition of return value context is moderate.

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 only two sentences, front-loaded with purpose and resource, then usage and return. No unnecessary words. Every sentence adds value, making it highly 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?

The tool has 4 parameters, 3 actions, and no output schema. The description covers the high-level purpose and return value ('merged or written result') but lacks detail on conflict resolution for sync, error handling, or return format. It is adequate but leaves gaps for a complex tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and their meanings (action enum, force, merge, path). The description adds no new parameter-level insights, matching the baseline of 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?

The description clearly states the tool synchronizes context between GEMINI.md and project.faf, with explicit verbs (import, export, sync). It distinguishes from sibling tools like faf_sync by specifying the Gemini CLI convention, making its domain unique.

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 provides a clear use case: 'keep a Gemini context file and your .faf in agreement from one source.' It implies the context and purpose, but does not explicitly mention when not to use it or offer alternatives, which would elevate it to a 5.

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

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

The description discloses that it 'fetches the repo and extracts its stack and context,' which is a key behavioral trait beyond the annotations. Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) are consistent. No contradictions. It adds value by explaining the fetching and extraction actions.

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: first states the main action and result, second gives usage guidance. No wasted words, front-loaded with the core purpose. Excellent structure.

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 simplicity (2 parameters, no output schema), the description covers the essential: what it does, how it works (fetches, extracts), and the two modes (write vs return). No missing information for an agent to use 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?

The schema has 100% coverage, describing both parameters (url, path). The description adds meaning: 'Returns the generated .faf' and explains path behavior ('if omitted, returns content without writing'). This enhances 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 clearly states the tool's action: 'Generate a project.faf from any public GitHub repository URL' with a specific verb ('Generate') and resource ('project.faf from GitHub URL'). It distinguishes from siblings like faf_init (for local projects) by specifying external fetching.

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 provides explicit guidance: 'Use this to bootstrap context for a project you have the URL for but not cloned locally.' This tells when to use the tool. It could be improved by explicitly stating when not to use (e.g., private repos), but the guidance is clear and helpful.

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 already provide readOnlyHint=false and destructiveHint=false. The description adds that it returns what was written, which is useful. However, it does not describe the synchronization process in detail or any potential side effects beyond the sync itself. Given annotations cover safety, a 3 is appropriate.

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

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

Two sentences, no wasted words. The main action is front-loaded, and the alternative is mentioned 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?

Given the tool's simplicity (1 optional param, no output schema), the description plus schema/annotations cover purpose, usage, behavior, and parameter. It could briefly explain what 'sync' entails, but overall it's complete enough for a focused 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% for the single parameter 'path', which already has a description stating it sets session context. The description does not add any additional meaning or context for the parameter, 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?

The description clearly states that the tool syncs a project.faf with CLAUDE.md to keep them aligned. It distinguishes from the sibling faf_bi_sync, which handles multiple targets. The verb 'sync' and resource 'project.faf with CLAUDE.md' are specific.

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: for the single CLAUDE.md target, and when not: use faf_bi_sync for multiple files (AGENTS.md, .cursorrules, GEMINI.md). This provides clear guidance on choosing between siblings.

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

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

Annotations give readOnlyHint=true. Description adds behavioral context about what is checked (malformed, missing, contradictory data) and aligns with read-only nature. No 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 concise sentences, front-loaded with action, then what it checks, then usage scenario. 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?

Given no output schema, description could specify the format of trust metrics or return value more clearly. Still adequate for a validation 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?

Zero parameters with 100% schema coverage, so baseline is 4. Description needs no further param 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 states 'Validate a project.faf for structural integrity and field consistency' with a specific verb and resource, and clearly distinguishes from sibling tools like 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 confirm the context is sound before relying on it or syncing it to other formats', providing clear context for use, though no explicit when-not-to or alternatives.

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