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 that the tool determines a classification, but does not indicate if it is read-only, side-effect-free, or what the return format is.

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 with no wasted words. It is concise and 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?

The tool has one required parameter and no output schema. The description does not explain the meaning of FULL, DELTA, X-DELTA, nor what the output looks like, leaving the AI agent without sufficient context.

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 already describes the single parameter 'topic' with 'Topic to check'. The description adds no extra meaning. With 100% schema coverage, baseline score is 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 uses a specific verb 'Determine' and specifies the resource 'topic' and the possible outcomes (FULL, DELTA, X-DELTA). However, the jargon 'soul' is unexplained, which slightly reduces clarity.

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 siblings like 'faf_analyze' or 'get_soul'. The description lacks context for choosing this tool over 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 mentions 'Two WASM calls, sub-millisecond total,' providing performance insight. However, with no annotations, it fails to disclose safety traits (e.g., read-only, side effects) or authentication requirements, leaving gaps in 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?

The description is concise at one sentence, front-loading key information about return values and performance. It is efficient but could be slightly more structured with separate sentences for clarity.

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

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

With no output schema, the description compensates by listing return fields (score, tier-ready, valid, engine identifier). It lacks error handling or input validation details, but for a single-parameter tool, it provides sufficient context.

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, and the description restates 'Raw .faf YAML content' with no additional semantic details. This meets the baseline but adds no extra value 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 it is a composite returning score, tier-ready, valid, and engine identifier, distinguishing it from sibling tools like faf_score, faf_validate, and faf_get_tier. However, it lacks a specific verb indicating the action (e.g., 'analyzes') beyond the name.

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 phrase 'One-call composite' implies using this when all analyses are needed, but it does not explicitly state when to avoid or use alternatives. The presence of sibling tools provides context but is not explained in the description.

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 fully compensates by noting 'Sub-millisecond, zero allocations', indicating non-destructive, high-performance read operation. 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 sentences, front-loaded with purpose and key differentiators. Every sentence adds value; 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 parameter and no output schema, the description covers what it does, how it works (engine), performance, and usage context. No 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 coverage is 100%, so baseline is 3. The description adds minor extra meaning ('arbitrary content', 'Zig WASM engine') but not significant syntactic detail beyond the schema's description of 'content'.

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 'Estimate token count for arbitrary content', providing a specific verb and resource. Among sibling tools, this is unique (no other token estimation tool), so it distinguishes well.

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 explicitly says 'Useful for context-budget planning', which gives clear context for when to use. However, it does not mention when not to use or suggest alternatives, so it's very good but not perfect.

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 present, so the description carries full burden. It discloses the return format (tier symbol) and references a canonical table, but does not mention error handling or side effects. For a read-only mapping, this is 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 focused sentence with no redundancy, front-loading the main action and result. Every word is necessary.

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 (single parameter, no output schema, no annotations), the description fully captures its purpose, input, and return value. No additional information is required for correct use.

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 with a clear description of 'score' (Numeric score 0-100). The description adds value by linking the parameter to the tier-mapping context, exceeding the schema's basic description.

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 action ('resolve') and resource ('tier'), specifies the input (numeric score) and output (tier symbol), and distinguishes it from siblings by focusing on a specific mapping task.

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 clear context for when to use the tool (given a numeric score needing tier resolution) but does not explicitly mention when not to use it or compare with sibling tools. The context is sufficient for a simple lookup.

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 full burden. It discloses behavioral traits: returns a Recommendation with hints, distinguishes light-lane (WASM, no FS) vs heavy-lane (full FS), and notes it is advisory-only. While it does not cover all edge cases, it provides adequate transparency for most use cases.

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

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

The description is front-loaded with the main action and is structurally sound. It includes necessary details about execution modes and return type. However, it is slightly verbose with execution lane details that could be bulleted; overall, each sentence 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 and 5 parameters, the description adequately explains the return structure and functional scope. No output schema exists, but the description briefly mentions the Recommendation fields. It could elaborate on the return fields further, but it is reasonably complete for the tool's purpose.

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 all 5 parameters described. The description does not add significant extra meaning beyond the schema; it reiterates the content types but provides no additional semantic value per parameter. 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 verb: it takes raw content strings and runs drift+contradiction signals to return a Recommendation. It specifies the resources (FAF substrate) and distinguishes from sibling tools like delta_check or faf_analyze by focusing on orchestration of multiple signals.

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 context by explaining two execution lanes and emphasizing 'Advisory only — never auto-fires'. However, it lacks explicit guidance on when to use this tool versus its siblings, such as delta_check or faf_validate. The usage is implied but not formally stated.

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 the return range, performance claim, and engine parity, but does not mention side effects, authorization needs, or that it is likely read-only.

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, front-loaded with the core functionality, and every sentence contributes meaningful information without 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?

For a simple tool with one parameter and no output schema, the description covers input semantics and return value. However, it lacks interpretation of what the score indicates, which could help an agent decide when to use this tool.

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

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

Schema coverage is 100%, but the description adds value by explaining that souls with a [faf] section have it extracted automatically, which is beyond the schema's parameter description.

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 scores .faf YAML content using a specific engine and returns a capped value (0-100). However, it does not differentiate 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 provides no guidance on when to use this tool versus alternatives. It mentions performance ('sub-ms at the edge') but does not specify use cases 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?

Discloses the use of the Mk4 Zig-WASM engine and the boolean return condition (true if mission-ready >= 100). Without annotations, this provides reasonable behavioral insight for a simple read-only validation tool, though side effects or error handling are not mentioned.

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

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

The description is two sentences with no unnecessary words, front-loading the purpose and returning a clear condition. 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 simplicity (one parameter, no output schema), the description covers the validation engine, input type, and return condition. It would benefit from clarifying error behavior (e.g., does invalid YAML throw an error?), but overall is adequate.

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 a clear description of the 'content' parameter. The description adds engine context but no additional semantic value beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Validate' and the resource '.faf YAML content', with a specific condition (returns true if >= 100). It distinguishes from sibling tools like faf_analyze by focusing on validation against a readiness threshold.

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 validation but does not explicitly state when to use this tool over siblings like faf_analyze or faf_score. No guidance on prerequisites 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?

No annotations are provided, so the description carries full burden. It discloses key behaviors (no cloning, extraction from README/package.json, returns content/score/metadata). It lacks details on rate limits, auth requirements, or caching, but covers the main non-obvious aspects.

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

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

Three sentences efficiently convey the core action, key constraint (without cloning), and outputs. Every sentence adds value without 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?

Despite lacking an output schema, the description explains the return values (.faf content, quality score, metadata). It covers the tool's inputs and outputs well for its complexity, though error handling is not mentioned.

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' is fully described in the schema (100% coverage). The description adds value by explaining accepted formats (URL or owner/repo) and the context of using it for a public repository. This goes beyond the schema's minimal description.

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 generates a .faf file from a public GitHub repo without cloning, extracts 6 Ws from README, analyzes stack, and generates AI context. It distinctly differentiates from sibling tools like refresh_faf 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 specifies it works for any public GitHub repo and emphasizes no cloning, which guides usage. However, it does not explicitly state when to prefer this over siblings like faf_analyze or faf_score, lacking clear 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states that the tool returns structured AI context, without mentioning any side effects, authentication requirements, rate limits, or error conditions. This is insufficient for a full understanding of behavioral traits.

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 very short, containing only two sentences, and is front-loaded with the core action. It is efficient, but could still be slightly more informative without adding much length. It earns its place but leaves room for improvement.

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 absence of an output schema and annotations, the description should provide more context about return values, error states, and usage notes. The phrase 'structured AI context' is vague and does not help the agent anticipate what to expect. For a simple fetch tool, it is adequate but not 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 coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for the 'soul' parameter. The schema description 'Soul identifier (e.g., "spacex", "wolfe", "grok")' is clear enough, so the description does not need to add more.

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 fetches a context soul by name and returns structured AI context. It uses a specific verb and identifies the resource, making the purpose unambiguous. However, it does not differentiate from sibling tools like list_souls or search_context, which could cause confusion about when to use each.

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 such as list_souls or search_context. It does not mention prerequisites, conditions, or exclusions, leaving the agent to infer usage context without help.

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 must disclose behavioral details, but it only states 'List all available context souls' without mentioning pagination, performance implications, or any side effects, leaving significant gaps.

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 single-sentence description is extremely concise and front-loaded with essential information, containing no redundant 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 complexity is low (no parameters, no output schema), the description is minimally adequate but lacks clarity on what constitutes a 'soul', what 'available' means, and whether the list is exhaustive or limited, leaving room for ambiguity.

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 and 100% schema coverage, so the description adds no additional meaning. The baseline score of 4 is appropriate since no parameters require explanation.

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 'list' and identifies the resource 'available context souls', making the tool's purpose immediately clear and distinguishing it from sibling tools like 'get_soul' 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 is provided on when to use this tool versus alternatives such as 'get_soul' for a specific soul or 'search_context' for filtered queries. The description lacks context for appropriate 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 must carry the burden. It states 'list' indicating a read operation, but lacks details on behavior for missing souls, error cases, or performance implications. Minimal disclosure.

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 is clear, front-loaded, and contains no wasted words. It efficiently conveys the tool's action and output focus.

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 largely sufficient. However, it could benefit from briefly noting the return format or possible errors, which would increase 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 for the single parameter 'soul', which is described as 'Soul identifier'. The tool description does not add extra meaning beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states the verb 'list', the resource 'unique tags', and the scope 'in a soul, with counts'. It effectively distinguishes from siblings like search_by_tag or tag_intel.

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 usage for getting an overview of tags with counts, but lacks explicit guidance on when to use this tool versus alternatives like search_by_tag or delta_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?

No annotations are provided, so the description must fully disclose behavior. It specifies the scorer type and drift reporting, but does not mention side effects, permissions, or whether the tool mutates state. The behavioral traits are partially detailed but lack completeness.

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

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

The description is front-loaded with the main action but includes a somewhat poetic second sentence ('The explicit re-grounding primitive...') and a meta note ('Built for Grok, by request'). Could be slightly more concise, but overall acceptable.

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 should clarify return structure. It mentions 'stamped re-ground' and 'stamped delta + summary', but these are vague. No mention of error handling or prerequisites. Given the moderate complexity (3 params, no output schema), the description is 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?

Schema description coverage is 100%, so the schema already defines parameters. The description adds context for 'baseline' (drift delta reporting) and 'verbatim' (default behavior), but does not significantly enhance beyond the schema. Baseline score 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 specifies the verb 're-ground', the resource '.faf content', and distinct actions (re-score, report drift, return stamped). It differentiates itself from sibling tools like faf_score by emphasizing 'long sessions' and 'drift → refresh → re-grounded', making its unique purpose clear.

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 usage for long sessions needing re-grounding ('The explicit re-grounding primitive for long sessions'), but does not explicitly state when not to use it or provide alternatives among the siblings. The context is implied rather than explicit.

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

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

Since no annotations are provided, the description alone must disclose behavior. It is minimal, merely stating the action without revealing any side effects, authorization needs, rate limits, or any other behavioral details beyond basic search functionality.

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 a single sentence. It is well-structured and front-loaded with the verb and resource. However, it could be slightly more informative without becoming verbose, hence not a perfect score.

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

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

Given the tool's simplicity (2 params, no output schema), the description is adequate in explaining inputs and action. However, it lacks information about the return value or the meaning of 'soul' and 'entries', which might be assumed but is not explicitly stated.

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 provides descriptions for both parameters ('Tag to search for' and 'Soul identifier'), achieving 100% coverage. The tool description does not add additional meaning beyond what is already in the schema, so a baseline score 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 action ('Find') and the resource ('all entries in a soul with a specific tag'), making the tool's purpose unambiguous. It distinguishes itself from siblings like 'list_tags' (lists all tags) and 'search_context' (likely searches context), ensuring an agent can select the correct tool.

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 or when not to use it. The description does not mention any prerequisites, exclusions, or sibling comparisons, leaving the agent without contextual usage instructions.

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 should fully disclose behavior. It states returns matching lines and is token-efficient, good for a read operation. However, it doesn't explicitly confirm no side effects or safety, leaving minor gaps.

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, immediately front-loaded with purpose and key feature. 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 hints at return format ('matching lines only'), which is helpful. Could be more detailed (e.g., structure of lines), but sufficient for a straightforward search 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 covers 100% of parameters. Description adds no extra meaning beyond schema description (soul optional, query required). Baseline 3 is appropriate as schema does the heavy lifting.

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

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

Description clearly states the tool performs full-text search across souls, highlighting a key feature (returns lines only) and token efficiency. This distinguishes it from siblings like search_by_tag or get_soul.

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 like search_by_tag or get_soul. The description implies usage for full-text search but lacks 'when not to use' or comparative context.

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 'discover' but does not disclose whether it is read-only, what is returned, or any side effects. Minimal behavioral context beyond the high-level functionality.

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 conveying key features efficiently. No wasted words, but could be structured with bullet points or clearer separation of core functionality vs. optional feature.

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?

Adequate for a simple tool with one optional parameter and no output schema. Covers main actions but lacks details on return format or behavior. With more siblings, additional context on when to use this vs. other analysis tools would improve 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?

Only one parameter (handle) with schema coverage 100%. The description adds 'optionally suggest tags for a specific namepoint,' which mirrors the schema description. Baseline of 3 is appropriate as the description 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?

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

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?

Implies usage for tag intelligence tasks and optionally for a specific handle, but no explicit when-to-use or when-not-to-use compared to siblings like faf_analyze or search_context. The context from sibling names provides some guidance, but the description lacks direct differentiation.

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