Persistent Project Context for xAI Grok

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

No annotations are present, so the description carries the full burden. It only states the tool 'determines' a classification, but does not disclose whether it is read-only, has side effects, requires authentication, or what the output format is. The behavioral aspects are insufficiently described.

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 immediately states the tool's purpose. It is efficient with no unnecessary words. Every part of the sentence contributes to understanding.

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 and lack of output schema, the description should clarify the return value or result format. It does not. The use of jargon ('soul') without explanation assumes domain knowledge. The description is incomplete for an agent to understand the full behavior and output.

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 provides a basic description ('Topic to check') but the tool description adds meaning by explaining that the topic is evaluated to determine which type of soul is needed (FULL, DELTA, X-DELTA). This connects the parameter to the tool's output, adding value beyond the schema's single-line 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's function: determining if a topic needs FULL, DELTA, or X-DELTA soul. The verb 'determine' and the resource 'topic' are specific. However, the term 'soul' is domain-specific and not explained, slightly reducing clarity. It differentiates from sibling tools like 'get_soul' and 'list_souls' by focusing on classification.

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. There is no indication of prerequisites, exclusions, or scenarios where other sibling tools would be more appropriate. The description lacks any usage 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?

With no annotations provided, the description carries full burden. It mentions two WASM calls and sub-millisecond performance but omits side effects, error handling, idempotency, or authorization requirements.

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 with no wasted words. Front-loaded with key outcome ‘score, tier-ready, valid’ and performance detail. Highly efficient.

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

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

No output schema exists and annotations are absent. The description does not explain the return format, meaning of fields like 'tier-ready', or error scenarios. Insufficient for 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 coverage is 100%, so the description adds no new meaning beyond what the schema already provides (raw .faf YAML content). 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 it is a one-call composite returning score, tier-ready, valid, and engine identifier. It distinguishes itself from siblings like faf_score, faf_get_tier, and faf_validate by offering a combined result.

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 use as a composite alternative to individual calls but lacks explicit guidance on when to use this tool versus running separate tools. No exclusions or prerequisites mentioned.

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 caching (KV-cached, 1h TTL) and required secret, but no annotations are provided, and it does not cover all behavioral aspects like rate limits 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?

Description is three sentences, front-loaded with phase info, then core. Could be slightly more concise, but 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?

Explains return format (content, score, file), caching, and prerequisites. Lacks output schema, so description adequately covers what is returned.

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. Description adds no extra detail about 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?

Clearly states it performs semantic search over a Grok Collection, specifying the verb 'search' and resource, and distinguishes from faf_section by mentioning composition for hybrid 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?

Provides clear context by mentioning composition with faf_section for hybrid retrieval, implying when to use each. Lacks explicit when-not-to-use instructions for other siblings.

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

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

No annotations provided, so description covers performance (sub-millisecond, zero allocations) and engine. Simple read operation; no destructive or auth info needed.

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

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

Two concise sentences. First sentence states purpose and technology; second adds performance and use case. 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 low complexity (1 string param, no output schema), the description fully covers purpose, performance, and intent. Complete for a utility 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% with a description. The description adds context (arbitrary content, use case) beyond the schema, enhancing understanding.

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

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

Clearly states it estimates token count for arbitrary content. Specifies engine (Zig WASM). Distinct 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?

Suggests use case 'context-budget planning'. Does not explicitly exclude alternatives, but the tool's singular purpose makes it clear when 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 provided, the description carries the full burden of behavioral disclosure. It details the core behavior (scoring, token estimation, deterministic verdict) and mentions an edge case ('hold-hint can't list empty slots at the edge'). However, it does not explicitly state whether the tool has side effects, such as modifying data, or require specific permissions. Since it returns a verdict, it is likely read-only, but this is not confirmed.

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

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

The description is relatively concise at about four sentences, with the key purpose stated upfront. It avoids redundancy but includes some technical jargon ('edge Mk4', 'Grok Collection', 'local gate') that may be necessary for domain context. The last sentence about 'hold-hint' is somewhat cryptic but adds specific detail.

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?

While the description explains the tool's logic, it lacks critical details about the output format (e.g., what the verdict looks like) and does not mention possible error conditions or prerequisites. Since there is no output schema, the description should clarify what the agent will receive. This omission reduces 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 with descriptions for all three parameters, so baseline is 3. The description adds value by explaining how the parameters are used in the promotion condition ('Promote IFF score >= min_score AND tokens <= max_tokens') and providing default values (85/8000). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose as a Phase III pre-promotion quality gate that scores .faf content, estimates tokens, and returns a deterministic promote/hold verdict. It specifies the exact condition for promotion ('IFF score >= min_score AND tokens <= max_tokens'), and distinguishes itself from sibling tools by being specifically designed for pre-promotion to a Grok Collection, with mention of 'Edge parity with the local 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?

The description provides clear context for when to use this tool: before content goes into a Grok Collection, as a pre-promotion gate. It implies that this is the final check before promotion. However, it does not explicitly state when NOT to use it or list alternative tools, though the context is sufficient for an agent to infer usage.

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

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

No annotations are provided, so the description must disclose behavioral traits. It mentions the tier table but does not explicitly state that the operation is read-only, idempotent, or side-effect-free. This is a minor gap given the simplicity of the 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 a single, concise sentence that contains no redundant information. It is front-loaded with the primary action and output.

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 adequately explains the return value (tier symbol). It does not describe error handling or edge cases, but for a simple mapping tool without required parameters beyond the score, this is sufficient.

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

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

Schema description coverage is 100%, so the description does not need to add parameter details. It only mentions 'numeric score', which aligns with the schema. No additional semantics or formatting guidance 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 the action ('Resolve the FAF tier') and the resource ('given numeric score'), and specifies the output symbol types. It distinguishes its purpose from sibling tools which cover different domains like analysis, collections, validation, etc.

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 when a numeric score needs a tier mapping. While it does not explicitly list when not to use or alternatives, the context of sibling tools makes the scope clear enough for an AI agent to decide.

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 clearly states the tool is a read-only query ('SELECTS facts, never grades them') and preserves provenance, though it omits details like side effects or auth requirements.

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 key action and resource, no redundancy; every sentence earns its place, despite the cryptic 'Phase III (FRC)' prefix.

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 lacks details about return format or behavior on invalid input; with no output schema, more context on what the 'structured summary' looks like would be helpful for a query 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%, baseline 3, but the description adds value by explaining that omitting filters yields a structured summary and reaffirms parameters (type/tag/priority/text), enhancing understanding 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 queries a durable .fafm model by type/tag/priority/text, distinguishing it from sibling tools like faf_score by explicitly noting it selects facts and never grades them.

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 when to use (to retrieve facts) and contrasts with scoring tools, but lacks explicit guidance on when not to use or which sibling is the best alternative.

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 full burden and does well: it discloses execution modes (WASM-pure vs FS access), advisory nature, and output structure. It lacks details on error handling or idempotency but covers key 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 efficiently structured, front-loading the core functionality in the first sentence. Every sentence adds distinct information without redundancy, making it easy to parse for an AI agent.

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 comprehensively explains the return value (Recommendation with recommend, severity, reason, summary, and hints). It covers input requirements, processing, and execution context, making it fully self-contained.

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%, and the description adds value by clarifying which parameters are required for meaningful analysis (e.g., faf is required, fafm enables drift detection). This goes beyond the schema's descriptions.

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

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

The description clearly specifies the tool's action: it takes raw content strings and runs deterministic drift + contradiction signals to produce a Recommendation. This is a specific verb-resource combination that distinguishes it from sibling tools like `delta_check` 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 clear context for usage, stating 'Advisory only — never auto-fires' and explaining light-lane vs heavy-lane execution. It implies when to use (when raw content is available) but does not explicitly mention 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 adds some behavioral context: returns capped score, uses engine, sub-ms performance. However, it doesn't explicitly state it's non-destructive or detail failure modes.

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, each providing unique information: scoring action, engine details, performance. No redundancy.

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

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

For a simple single-parameter tool, the description covers return range, engine, and performance. It lacks mention of error handling or output details, but overall 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?

The description adds value beyond the schema by noting that souls with a [faf] section have it extracted automatically, aiding understanding of the content parameter.

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 via a specific engine and returns a capped score of 0-100. It does not explicitly differentiate from sibling tools, but the purpose is 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 on when to use this tool versus other faf_* siblings. No prerequisites or exclusions mentioned.

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 fully discloses behavior: returns exact, whole sections with structure preserved, and lists all paths when omitted. It does not cover side effects or error handling, but for a read-oriented tool 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, efficient sentence that conveys core functionality, examples, and a usage tip with no redundant information.

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

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

Given no output schema and two parameters, the description explains the tool's purpose and behavior sufficiently. It could mention expected return format if section not found, but overall it is complete for a simple retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal new meaning beyond the schema examples and 'omit to list paths' instruction, which are already present in the schema 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 it returns exact .faf sections by dotted path, preserving structure. It uses specific verbs and examples, but the 'Phase III (FRC)' jargon and lack of explicit sibling differentiation lower the score slightly.

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 hints at being a complement to blind chunking, suggesting when to use it, but does not explicitly name alternatives or provide when-not-to-use guidance. The note about omitting 'section' to list paths is helpful but not sufficient for tool selection among siblings.

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

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

No annotations provided, so the description bears the burden. It discloses the engine used and the exact return condition. The tool appears to be a read-only validation with no side effects, which is adequately clear.

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, no filler, and front-loaded with the key action and engine.

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 provides sufficient context about the operation and the return value condition. It could have mentioned potential errors or side effects, but these seem unlikely for a validation function.

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 'content' has 100% schema description coverage. The description adds the context that the content is YAML and validation is with a threshold, but does not significantly augment the schema's meaning.

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

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

The description clearly states the tool validates .faf YAML content using the Mk4 Zig-WASM engine, with a specific success condition (returns true if mission-ready >= 100). It distinguishes itself from sibling tools like faf_analyze or faf_score by focusing on validation.

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 checking .faf content readiness, but provides no explicit guidance on when to use this tool versus alternatives like faf_gate or faf_score. No exclusions or prerequisites are mentioned.

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 it does not clone (read-only), extracts from README and package.json, and returns .faf content, quality score, and metadata. This is comprehensive, though it omits details like error handling or rate limits.

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 but packs all essential information: purpose, no-clone, extraction details, return values. Every part earns its place, and the key point 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 single parameter and no output schema, the description explains what the tool does and what it returns. It's complete enough for an agent to decide to use it, though it could mention limitations (e.g., dependency on README existence).

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 one parameter. The description adds the constraint 'public' and explains the format (URL or owner/repo). This adds value beyond the schema's 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 verb 'Generate' and resource 'faf file' with source 'from GitHub' is specific. It clearly states the action and output, distinguishing it from sibling tools like faf_analyze or faf_validate which likely operate on existing .faf files.

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

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

The description says 'from any public GitHub repository WITHOUT cloning', providing clear context for when to use. However, it does not explicitly mention when not to use or compare to other siblings, but the guidance is sufficient.

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 exist, so the description must disclose behavior. It only states it returns structured AI context, with no mention of side effects, permissions, or limitations for a fetch operation.

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 is concise, but it could be more informative without being verbose. Efficient but minimal.

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 fetch with one parameter, the description is adequate but lacks usage context and return details, especially since no output schema is provided.

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 description adds no meaning beyond the schema's field description. 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 tool fetches a context soul by name and returns structured AI context, distinguishing it from siblings like list_souls, search_by_tag, or 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 alternatives; no explicit context or exclusions provided.

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 behavior. The description only states it lists souls, but does not mention read-only nature, side effects, authentication needs, or output structure.

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

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

A single, complete sentence with no extraneous words. Front-loaded verb and resource.

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 no parameters and no output schema. The description does not elaborate on the structure of a 'soul' or any filtering/ordering. For a list tool, more detail on output fields would be expected.

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 no parameters, so baseline is 4. The description does not add parameter information, but none is needed.

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

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

The description explicitly states the verb 'List' and the resource 'all available context souls'. It clearly distinguishes from sibling tool 'get_soul' which likely retrieves a single 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 guidance on when to use this tool vs alternatives like 'search_by_tag' or 'list_tags'. No mention of exclusions 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, so the description carries full burden. It only states basic functionality without disclosing behavioral traits like pagination, performance, 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 a single concise sentence with no wasted words. However, it could be slightly more informative.

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 low complexity, the description is adequate but lacks information about output format or ordering, which would be helpful since there is no output schema.

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 single parameter 'soul' described as 'Soul identifier'. The description does not add extra meaning beyond the schema, meeting the baseline of 3.

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

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

The description clearly states the verb 'list', the resource 'unique tags', and the scope 'in a soul, with counts'. It distinguishes from sibling tools like 'search_by_tag' and '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 listing tags, but does not explicitly state when to use this tool versus alternatives or provide 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 carries the full burden. It discloses that the tool re-scores via a specific scorer, reports drift against an optional baseline, and returns a stamped re-ground. It mentions honoring the authored app-type shape, but does not detail side effects or permissions. Overall, it provides sufficient transparency for an agent.

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 three sentences, front-loading the main action. Every sentence adds value without redundancy. 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?

Despite no output schema, the description explains the return format sufficiently: 'stamped re-ground' with options for full content or summary. Given the moderate complexity (3 params, no nested objects) and good schema coverage, the description is 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% with descriptions for all three parameters. The description adds value by explaining the baseline parameter's drift delta calculation and the verbatim option's output format (stamped delta + summary vs. full content). This goes slightly beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Re-ground on .faf content — re-score via the Mk4 Zig-WASM Enterprise scorer... and return a stamped re-ground.' It specifies exact action (re-ground), resource (.faf content), and unique mechanism, distinguishing it from sibling tools like 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 provides usage context: 'The explicit re-grounding primitive for long sessions: drift → refresh → re‑grounded.' This implies when to use the tool, but lacks explicit guidance on when not to use it or comparisons to alternatives like faf_score.

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

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

No annotations are provided, so the description must carry the full burden. It only states the action without disclosing behavioral traits such as read-only nature, pagination, error handling, or permissions. The description adds minimal value beyond the name.

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, highly concise and to the point. No unnecessary words, but could be slightly more structured to improve readability.

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 and only two simple parameters, the description is minimally complete. It lacks details on output format, potential limits, or what 'entries' refers to, but is adequate 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 coverage is 100%, with both parameters described in the schema. The description does not add any new meaning beyond what the schema provides, so 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?

The description clearly states the action ('Find') and the resource ('entries in a soul with a specific tag'). It distinguishes from siblings like list_tags (which lists tags) and search_context (likely broader search), making the purpose specific and 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 implies usage for searching entries by tag within a soul, but provides no explicit guidance on when to use this tool versus alternatives like search_context or tag_intel, nor any exclusions or limitations.

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 fully bears transparency burden. Clearly states it performs full-text search and returns only matching lines (token-efficient). No contradictory or omitted behavioral 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?

Two concise sentences, front-loaded with verb and resource, no extraneous words. Efficient and scannable.

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

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

No output schema, but description explains return format (matching lines only) and efficiency. Covers key aspects for agent decision-making; could mention result structure or limitations.

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 description adds minimal value over schema. Merely restates scope ('across souls') without enriching parameter meaning or providing examples.

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

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

Description specifies verb (search), resource (souls), and key behavioral trait (returns matching lines only, token-efficient). Distinguishes from sibling tools like search_by_tag (tag-based) and faf_collections_search (FAF-specific).

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

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

Implied usage for full-text search across souls, but no explicit when-not-to-use or comparison to alternatives. Lacks guidance on when to prefer this over siblings like search_by_tag or faf_analyze.

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 must carry full burden. It states the tool discovers and suggests, implying read-only behavior, but fails to explicitly disclose non-destructive nature, required permissions, or any side effects. The lack of behavioral details is a significant 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?

Two sentences with no wasted words. First sentence captures main purpose immediately, second adds optional functionality. Efficient and 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 outlines what the tool returns (patterns, co-occurrence, candidates, merge suggestions) but lacks detail on format or examples. For a simple tool with one optional param, it is adequate but not fully comprehensive.

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 single optional parameter 'handle' described in schema. Description adds 'Optionally suggest tags for a specific handle', which closely mirrors the schema description, providing minimal additional meaning beyond the schema.

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

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

Description uses specific verb 'discover' and noun phrases 'tag patterns, co-occurrence, candidates, and merge suggestions' to clearly state what the tool does. It distinguishes from siblings like 'list_tags' (simple listing) and 'search_by_tag' (search by tag) by focusing on pattern 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?

No explicit guidance on when to use this vs alternatives. The description implies usage for pattern discovery rather than simple listing, but does not provide when-not-to-use or compare with 'list_tags' or 'search_by_tag'.

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