claude-faf-mcp

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

No annotations exist, so the description must fully disclose behavior. It only states 'Determine if...' without clarifying whether this is a read-only check, what side effects occur, or how the result is returned. The lack of behavioral details makes it hard for the agent to anticipate outcomes.

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 a single sentence, which is concise. However, it lacks structure and front-loading of critical information; it does not highlight the core action or constraints. Every sentence is present, but the tool's purpose could be more succinctly stated with key details.

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 one parameter and no output schema, yet the description does not explain what 'soul' means, how the result is interpreted, or what the possible return values are. Given the jargon and lack of context, the description is incomplete and leaves the agent guessing.

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 describes 'topic' as a required string. The description adds no additional meaning beyond the schema, such as what constitutes a valid topic or examples. With high 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.

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

The description clearly states the tool determines if a topic needs FULL, DELTA, or X-DELTA soul, using a specific verb and resource. However, the term 'soul' is jargon that may not be universally understood, and the description does not differentiate it from sibling tools like 'get_soul' or 'faf_gate'.

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

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

No guidance is provided on when to use this tool versus alternatives like 'faf_validate', 'get_soul', or 'faf_score'. The description does not include context, prerequisites, or exclusions, leaving the agent without decision support for tool selection.

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

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

No annotations provided, so description carries full burden. Only mentions performance (two WASM calls, sub-millisecond), but lacks disclosure of errors, idempotency, 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.

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

Very concise, two sentences, no unnecessary words. However, could be more structured or informative without being verbose.

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 it's a composite tool with no output schema and many siblings, the description is incomplete. Lacks explanation of output structure, 'tier-ready', 'engine identifier', and when to prefer this over individual calls.

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 description for the single parameter. The tool description adds no additional meaning beyond what the schema provides.

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

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

The description clearly states it's a composite tool returning score, tier-ready, valid, and engine identifier, distinguishing it from sibling tools like faf_score, faf_get_tier, faf_validate.

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?

Implied use when wanting comprehensive results in one call, but no explicit guidance on when to use vs alternatives or when not to use.

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

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

With no annotations, the description carries the full burden. It discloses caching (KV-cached, 1h TTL), authentication requirements (XAI_API_KEY secret), environment handling (env-aware), and return format (chunks with content, score, file). This is thorough, though error behavior is not detailed.

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, with each sentence adding relevant information (purpose, caching, auth, composition). It could be slightly streamlined by reducing domain-specific jargon like 'Phase III (FRC §7b)', but overall it is well-structured.

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 provides sufficient context: purpose, return structure (chunks with content, score, file), caching, auth, and integration with faf_section. It covers the essential aspects for a search tool, though error handling and pagination are omitted.

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 descriptions already cover all three parameters clearly (query, collection_id, limit with default). The description adds no further parameter semantics beyond the schema, so a baseline of 3 is appropriate given 100% schema coverage.

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 performs 'semantic search over a Grok Collection' and specifies the output fields (content, score, file). It also distinguishes itself from the sibling tool faf_section by noting they compose for hybrid retrieval, making the purpose distinct.

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 mentions composing with faf_section for hybrid retrieval, which implies a use case, but it does not explicitly state when to use this tool vs. alternatives or provide exclusion criteria. No 'when to use' or '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.

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

No annotations are provided, so the description must carry the full burden. It discloses sub-millisecond speed and zero allocations, which are key behavioral traits, but does not discuss error handling, input size limits, or other edge cases. Adequate for a simple estimation 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 extremely concise: two sentences, no wasted words. It front-loads the primary action and includes relevant performance details and use case.

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 (one parameter, no output schema), the description is nearly complete. It covers purpose, performance, and use case. The only minor gap is lack of explicit error or edge-case information, but for a low-complexity tool this is acceptable.

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

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

Schema description coverage is 100% for the single parameter. The description adds 'arbitrary content' which reinforces the parameter's purpose but does not significantly extend beyond the 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?

The description clearly states the tool estimates token count for arbitrary content, mentions the underlying engine (Zig WASM), and distinguishes itself with performance metrics. No sibling tool performs token estimation, so it stands out.

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 mentions it is useful for context-budget planning, providing a hint of when to use it, but does not explicitly state when not to use it or compare with alternatives. Given the tool's uniqueness, this is adequate but minimal.

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

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

With no annotations, the description carries the burden. It discloses that the tool scores, estimates tokens, and returns a deterministic verdict with defaults. It also mentions a specific behavioral trait: 'the hold-hint can't list empty slots at the edge.' However, it does not explicitly state whether the tool is read-only or has side effects, leaving some ambiguity.

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 four sentences long, front-loaded with purpose and key conditions. Every sentence serves a purpose, though the last sentence about 'hold-hint' is somewhat cryptic and may not be essential for general understanding. It is efficient but not perfectly concise.

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 description explains the tool's logic and parameters adequately, but lacks details about the return value format (e.g., what a 'promote/hold verdict' looks like) and does not address safety or idempotency. Given the absence of annotations and output schema, these omissions leave gaps for an agent to use the tool 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?

Input schema already describes each parameter well (100% coverage). The description adds value by explaining the promotion logic that relates the parameters: 'Promote IFF score >= min_score AND tokens <= max_tokens.' This goes beyond mere parameter descriptions and clarifies how they interact.

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 is a quality gate for .faf content, scoring and estimating tokens to produce a promote/hold verdict. It specifies the promotion conditions and defaults, and distinguishes itself from siblings like faf_score and faf_estimate_tokens by being a combined gate. The mention of Phase III and pre-promotion context adds precise purpose.

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 context for when to use this tool (before promotion to a Grok Collection, Phase III), but does not explicitly state when not to use it or what alternatives exist. It briefly mentions edge parity with the local gate but lacks comparison to sibling tools like faf_score or faf_estimate_tokens.

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

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

With no annotations, the description carries the full burden. It correctly implies a read operation and explains the output. However, it does not disclose handling of invalid inputs, authentication needs, or potential 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.

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

The description is two concise sentences with no wasted words. It front-loads the core purpose and adds the return format in a clear second sentence.

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 parameter, no output schema, and no annotations, the description adequately covers the main functionality and output. Minor missing details like edge case handling do not significantly detract from 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 the description adds no new meaning beyond the schema's description of the score parameter (numeric, 0-100). Baseline score is appropriate.

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

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

The description clearly states the tool resolves the FAF tier for a numeric score and specifies the return format (tier symbols). It distinguishes from siblings through its unique action and resource, though no explicit differentiation is provided.

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

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

No guidance is given on when to use this tool versus alternatives or when not to use it. There is no mention of context, prerequisites, or 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?

With no annotations, the description carries the burden of behavioral disclosure. It states the operation is a SELECT and preserves provenance, but does not mention permissions, side effects, or whether it is read-only. The mention of 'Phase III (FRC)' is cryptic and provides little transparency.

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 with no fluff. The first sentence states the action and filters; the second clarifies the non-scoring nature. Every word earns its place.

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 complexity (5 parameters) and absence of an output schema, the description is incomplete. It does not describe the return format, pagination, error handling, or output structure, leaving the agent to infer.

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 baseline is 3. The description adds value by noting that omitting all filters yields a structured summary, which is not in the schema. However, it does not elaborate on each parameter's format 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 clearly states the tool's purpose: querying a .fafm model by type/tag/priority/text. It distinguishes from siblings by explicitly stating it selects facts and never grades them, contrasting with the sibling tool '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?

The description suggests omitting filters for a structured summary, but provides no explicit guidance on when to use this tool over alternatives (e.g., when not to use it). It implicitly contrasts with scoring tools but doesn't name specific siblings or contexts.

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

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

No annotations are provided, so the description carries full burden. It discloses execution modes (light-lane vs. heavy-lane), advisory-only nature, and mentions stateful signals unavailable. It could benefit from mentioning any required permissions or side effects, but overall it is fairly transparent.

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 well-structured with a clear overview first, then details and conditions. It is reasonably concise, though the second sentence is somewhat long. Every sentence adds value without unnecessary elaboration.

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 lack of output schema and many sibling tools, the description provides adequate context: execution differences, advisory nature, output structure (Recommendation with hints). It could elaborate on the exact triggers for each signal, but overall it is complete enough for an agent to understand usage.

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% with each parameter well-described. The description adds a high-level explanation of how parameters are used but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool's purpose: it takes raw content strings and runs drift and contradiction signals to produce a structured Recommendation. The verb 'orchestrate' and mention of specific file types make the action distinct, but it does not explicitly differentiate from sibling tools like 'delta_check' or 'faf_analyze'.

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

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

The description implies use for obtaining a recommendation based on FAF content, and notes 'Advisory only — never auto-fires.' However, it does not explicitly state when to use this tool over alternatives (e.g., when to choose orchestrate vs. faf_gate or faf_analyze) or provide exclusion criteria.

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 behavioral traits: return range (0-100 capped), performance (sub-ms), and engine parity (same as xai-faf-rust and xai-faf-zig). No annotations are provided, so the description carries the full burden; it does so well but could mention error handling 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.

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

The description is extremely concise, with two sentences that immediately convey the core action and key details. Every sentence adds value, and the most critical information is front-loaded.

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 simplicity of the tool (one parameter, no output schema), the description covers the return value and performance. It could be enhanced by clarifying error behavior or preconditions, but it is largely 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?

The description adds value beyond the input schema by explaining automatic extraction of [faf] sections for souls. Although schema coverage is 100%, the description provides practical context that helps the agent understand the parameter's behavior.

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 purpose: scoring .faf YAML content via a specific engine, with a capped 0-100 return value. It distinguishes itself from siblings by mentioning the engine and parity with other tools, making its role 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 lacks guidance on when to use this tool over alternatives like faf_validate or faf_analyze. No exclusions or prerequisites are mentioned, leaving the agent without clear contextual differentiation.

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

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

With no annotations provided, the description carries the full burden. It conveys that the tool is a read-only retrieval (returns exact section) but does not explicitly state that there are no side effects or mutation. The phrase 'structure preserved' hints at non-destructive behavior, but explicit reassurance is missing.

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 at two sentences, front-loading key info. The 'Phase III (FRC)' prefix may be jargon but does not overwhelm. Every sentence adds value, though the second sentence could be slightly more structured.

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 simple tool (2 params, no output schema), the description is sufficient. It explains the exact retrieval nature and the listing capability. It could mention what happens if the path does not exist or if the input is malformed, but for a basic tool it is complete enough.

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% (both parameters described). The description adds the example 'stack.backend' and reiterates that omitting 'section' lists all paths, which largely duplicates the schema's own description. No additional semantics like formats or constraints are provided.

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 returns an 'EXACT, WHOLE .faf section by dotted path' and provides examples like 'stack' and 'human_context'. It distinguishes itself as the deterministic complement to blind chunking, making the purpose unambiguous.

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 explains when to use this tool (for exact section retrieval vs. blind chunking) and mentions that omitting 'section' lists all paths. However, it does not explicitly state when not to use it or provide clear differentiation from sibling tools like faf_analyze or faf_validate.

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

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

With no annotations, the description carries the full burden. It mentions the engine and the return value condition but does not disclose whether the tool is read-only, has side effects, or error behavior. The threshold detail adds some transparency, but more context on behavior is lacking.

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 extremely concise with two sentences that front-load the purpose and key detail. Every word earns its place with no fluff.

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 single parameter, lack of output schema, and no annotations, the description covers the core functionality and return value. However, it does not explain validation failure behavior (errors vs false) or edge cases, which would be helpful for a complete understanding.

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 for the single parameter is 100%, meaning the parameter is already well-described in the schema. The tool description adds no additional semantic value beyond what the schema provides, resulting in a baseline score 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 it validates .faf YAML content and specifies the engine (Mk4 Zig-WASM). It also clarifies the return condition (mission-ready >= 100). However, it does not differentiate itself from sibling tools like faf_analyze 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?

No guidance is provided on when to use this tool versus its many siblings. There are no directions about prerequisites, alternatives, or when not to use it.

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

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

With no annotations, the description covers key behaviors: no cloning, extracting from README, analyzing languages/package.json. However, it omits potential limitations (e.g., private repos, rate limits) and 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.

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

The description is concise (2-3 sentences) and front-loaded with the primary action. No unnecessary words, but could be slightly more structured.

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 a single required parameter and no output schema, the description adequately explains what is returned (content, quality score, metadata). Lacks mention of prerequisites or error cases, but sufficient 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?

The single parameter 'repo' has 100% schema description coverage, and the description adds examples of accepted formats (URL or owner/repo), aiding correct invocation.

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 purpose: generating a .faf file from a public GitHub repository without cloning. It specifies the extraction of '6 Ws' from README and analysis of stack, distinguishing it from sibling tools like faf_analyze or faf_validate.

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 does not provide guidance on when to use this tool versus alternatives. There are many sibling tools, but no exclusion criteria or context for choosing this one.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool 'returns structured AI context', which is moderately informative but lacks details on error conditions, permissions, or side effects. For a simple fetch operation, this is minimally adequate.

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 a single sentence that conveys the essential information without any fluff. It is front-loaded and earns its place.

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 (one required parameter, no output schema, no annotations), the description is largely complete. It explains what the tool does and what it returns. However, it could define what a 'context soul' is for better 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?

The input schema has 100% coverage and describes the 'soul' parameter with examples. The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate. The examples are helpful but not above expectations.

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 'Fetch a context soul by name' clearly states the verb and resource, distinguishing it from sibling tools like 'list_souls' which likely lists multiple souls. It specifies that it operates by name, making the tool's purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives like 'list_souls' or 'search_context'. The description only states what the tool does without any context for selection or prerequisites.

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

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

No annotations are provided, and the description fails to disclose any behavioral traits such as pagination, rate limits, or what 'available' means. It is too brief to help an agent understand the tool's behavior beyond the basic action.

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 a single, clear sentence with no wasted words. It is appropriately sized for a tool with no parameters and a simple action.

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 lack of output schema and annotations, the description is minimal. While the tool is simple, it does not explain what 'context souls' are or what the list contains, leaving some ambiguity for an agent.

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

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

The tool has zero parameters, so per guidelines the baseline is 4. The description does not need to add parameter meaning, and no information is missing in this dimension.

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 it lists all available context souls using a specific verb and resource. However, it does not distinguish itself from sibling tool 'get_soul', which might serve a similar but singular purpose.

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 no guidance on when to use this tool versus alternatives. With 18 sibling tools, including search_by_tag and search_context, the agent is left without context for choosing this one.

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

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

No annotations provided, so description carries full burden. It indicates a read operation for listing unique tags with counts, but lacks details on permissions, limits, pagination, or cost. Basic transparency is adequate for a simple list 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?

Single sentence, no fluff. Efficiently conveys the core purpose, though it could be structured to include more detail without sacrificing conciseness.

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?

Minimal description for a simple tool with one parameter and no output schema. It covers the basic purpose but omits details like return format or behavior. Could be more complete given the context of siblings.

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?

Input schema has 100% coverage with one required parameter 'soul' described as 'Soul identifier'. Description adds context by saying 'in a soul', but does not add new meaning beyond the schema. Baseline score 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?

Description explicitly states the tool lists all unique tags in a soul with counts, clearly distinguishing it from sibling tools like 'search_by_tag' which searches by tag, and 'tag_intel' which provides intelligence on tags.

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 explicit guidance on when to use this tool versus alternatives. The description implies usage for listing tags, but does not mention when not to use it or compare it to siblings like 'search_by_tag' or 'tag_intel'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the tool re-scores using a specific scorer and optionally reports drift, but it does not mention side effects (e.g., whether the re-grounding is stored or purely computational), permissions, or error states. The mention of 'stamped re-ground' gives some insight but lacks detail on mutability.

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 extremely concise: three sentences with no unnecessary words. It front-loads the core purpose ('Re-ground on .faf content') and immediately follows with key details (scorer, drift, stamp). Every sentence contributes 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 has 3 parameters and no output schema, the description does a good job explaining the return values ('stamped re-ground', 'stamped delta + summary', or full content with stamp). It also describes the high-level workflow. However, it could improve by specifying status indicators or error handling, which would make it more complete.

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 description adds significant meaning beyond the schema's basic parameter descriptions. It explains that 'content' is re-scored via a specific scorer, 'baseline' is an optional last-known score enabling drift reporting, and 'verbatim' controls return format. This provides clear, actionable context that the schema alone does not fully convey.

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 uses a specific verb ('re-ground') and resource ('.faf content'), clearly distinguishing this tool from siblings like 'faf_score' or 'faf_validate'. It also provides the context of being the explicit re-grounding primitive for long sessions, making its purpose unambiguous.

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 states this is 'the explicit re-grounding primitive for long sessions' and mentions a workflow ('drift → refresh → re-grounded'), implying when to use it. However, it does not explicitly state when not to use it or provide alternatives, which would elevate clarity further.

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

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

No annotations provided, so description carries full burden. It states 'find all entries' but doesn't disclose pagination, performance, or confirmation of read-only nature. Adequate but not thorough.

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?

One sentence of 11 words, no redundancy. 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 simple search tool with 2 parameters and no output schema, the description is complete enough. It tells what the tool does. Could mention return type but not critical.

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 basic descriptions. The description adds context that the tool searches for entries in a soul with a tag, which enriches the parameter meaning slightly 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 clearly states the action (find), resource (entries in a soul), and constraint (specific tag). It distinguishes from siblings like list_tags and search_context.

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

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

No guidance on when to use this tool versus siblings like search_context or tag_intel. No context on prerequisites or when not to use.

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

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

No annotations are provided, so the description carries full burden. It discloses key behaviors (returns matching lines, token-efficient), but lacks details on access requirements, rate limits, or any 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.

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

The description is extremely concise with two front-loaded sentences, no filler, and every word 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?

With no output schema, the description partially covers return format by stating 'returns matching lines only', but could be more specific about the structure. For a simple search tool, it is largely complete.

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 baseline is 3. The description adds value by noting the output is token-efficient, but does not elaborate on the two parameters beyond what the schema already provides.

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

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

The description clearly states the tool performs 'full-text search across souls' and specifies it returns matching lines only and is token-efficient, which effectively distinguishes it from sibling tools like 'search_by_tag'.

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

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

The description implies the tool is for full-text search, but does not explicitly provide when/not-to-use guidance or mention alternatives among the sibling tools.

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

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only operation but does not explicitly state that it does not modify state, nor does it mention performance, rate limits, or limitations. The lack of transparency for a discovery tool is a gap.

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 with no redundant information. It is front-loaded with the primary action and efficiently includes the optional parameter use case. No fluff.

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 lack of annotations and output schema, the description is minimally adequate. It covers the main purpose but does not explain the output format, error conditions, or limitations. For a tool with one optional parameter, it is somewhat incomplete.

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 optional parameter with a clear description. Schema coverage is 100%, so the description adds no extra value 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?

The description clearly states the tool's purpose: discover tag patterns, co-occurrence, candidates, and merge suggestions. It distinguishes from siblings like list_tags (which lists tags) and search_by_tag (which searches by tag) by focusing on intelligence rather than retrieval.

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 explicit guidance on when to use this tool versus alternatives. While the optional handle parameter suggests use cases, there is no mention of when not to use it or how it compares to list_tags or search_by_tag. The context is implied but not clarified.

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