Persistent Project Context for xAI Grok

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

The description adds useful behavioral context by indicating a read-only classification decision between FULL, DELTA, and X-DELTA. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. However, the description does not disclose the exact return shape or edge-case behavior, but this is somewhat mitigated by annotations.

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

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

The description is one concise sentence that immediately states the tool's core purpose and outcome categories. It avoids repetition and every word earns its place.

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

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

Though the tool is simple, there is no output schema and no explanation of the 'FULL/DELTA/X-DELTA' categories beyond their names. The description lacks the broader doctrinal context that would help an agent fully understand when and how to invoke the tool. It is minutely viable but not richly 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 for the 'topic' parameter is 100%, but the schema description is minimal ('Topic to check'). The tool description does not add extra meaning about topic formats, examples, or expected input granularity. With full schema coverage, a baseline of 3 is reasonable.

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 names a precise decision outcome space (FULL, DELTA, or X-DELTA soul). This distinguishes it from retrieval-oriented siblings like get_soul and list_souls. It is not a 5 because the term 'soul' is domain jargon that relies on unexplained 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?

The description gives no explicit guidance on when to use this tool versus alternatives. With 18 sibling tools such as faf_score, faf_validate, and get_soul, an agent must infer when a 'Delta Doctrine Check' is the right choice, which is a significant gap.

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

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

Annotations already declare that the operation is read-only, idempotent, and non-destructive. The description adds beyond annotations by disclosing the internal execution path: two WASM calls and sub-millisecond total latency. This gives the agent useful performance expectations and a sense of atomicity beyond the annotated safety hints.

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 wastes no words. The key behavioral point ('one-call composite') and the concrete return items are front-loaded, and the performance note adds meaningful context without padding. Every phrase 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?

There is no output schema, so the description must tell the agent what the tool returns. It does list score, tier-ready, valid, and engine identifier. Given the simple string input, this is sufficient for a read-only composite call. A bit more detail about the types or shape of each return field would make it fully complete, but the essentials are covered.

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?

Since the schema description coverage is 100%, the single `content` parameter is already fully documented as raw .faf YAML content. The description does not add further parameter details, but it is not required to because the schema carries the full burden. Baseline 3.

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

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

The description clearly states a specific resource (raw .faf YAML), verb (analyze), and the exact outputs it returns: score, tier-ready, valid, engine identifier. It also distinguishes itself from the many sibling tools by being a 'one-call composite' that returns everything at once. An agent can easily know what this tool does and how it differs from more focused tools.

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

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

The phrase 'One-call composite' implies that this tool is for when you need score, tier, and validation together, but it does not explicitly say 'instead of calling faf_score, faf_validate, and faf_get_tier separately' or describe when not to use it. Usage guidance is present only by implication, not explicitly.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. The description adds valuable operational behavior: 1-hour KV caching, edge execution, requirement for the XAI_API_KEY secret, env-aware handling, and the chunk return shape. It does not mention what happens if the secret or KV store is unavailable, but this is minor given the annotation coverage.

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 compact and front-loaded with the core operation. The factional reference 'Phase III (FRC §7b)' is mildly noisier for a general AI agent but doesn't hurt overall. No redundant padding.

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 search tool with only three parameters and no output schema, the description covers the needed selection, return, and operational context: what it searches, how it returns results, how it composes with faf_section, and what secrets/KV resources are required. The absence of an output schema is compensated by the explicit 'content, score, file' summary.

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 exceeds the baseline by clarifying that 'query' is semantic, not lexical, and that results take the form of matched chunks with content, score, and file. This adds meaning beyond the schema's simple field labels.

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 states a precise operation: 'semantic search over a Grok Collection', identifies the resource, and indicates it returns matched chunks. It also differentiates itself from the structural sibling faf_section and adds scoping ('edge', 'KV-cached'), so an agent can distinguish it from the many sibling tools.

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

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

It gives clear context: this is the semantic querying tool, and it can be composed with faf_section for hybrid retrieval. It does not explicitly provide 'when-not-to-use' exclusions, but the semantic/structural distinction gives enough guidance for 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?

The description adds performance and allocation behavior — 'Sub-millisecond, zero allocations' — which meaningfully supplements the annotations. It is consistent with readOnlyHint=true and idempotentHint=true since token estimation is a pure, non-mutating operation. No behavioral contradiction is present.

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 wasted words. The primary action leads, performance characteristics follow, and the use case closes the description compactly. Every clause 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?

For a single-parameter read-only tool with rich annotations, this description is largely sufficient. It covers the purpose, the performance profile, and the intended use case. It does not explicitly state the return type, but 'token count' strongly implies a number, so this is a minor absence rather than a critical gap.

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 documents the only parameter ('Content to estimate tokens for.') with 100% coverage, so the baseline expectation is met. The description reinforces that content is 'arbitrary,' which adds a small nuance about input flexibility, but it does not fundamentally expand on 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 verb-resource pair — 'Estimate token count for arbitrary content' — which exactly matches the tool name and title. The additional detail 'via the Zig WASM engine' and the framing around context-budget planning make the tool's role concrete and distinguishable from broader analysis tools like 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 gives a clear use context: 'Useful for context-budget planning.' This tells an agent when to reach for this tool. It does not explicitly contrast it against sibling tools like delta_check or faf_get_tier, but the use case is distinct enough to guide selection.

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

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

Annotations already show this is read-only and idempotent; the description adds meaningful behavioral context on top: the verdict is deterministic, based on score and token thresholds, and edge parity means the hold-hint cannot list empty slots at the edge. This gives the agent expectations beyond the annotations.

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

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

The description is compact, front-loaded, and every sentence carries distinct information: what the tool does, when it is used, the exact edge condition, and an edge-case caveat. No redundant filler or restating of structured field names.

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 read-only, single-required-parameter gating tool, the description provides enough context to know when to call it and what logic it applies. The main minor gap is that the exact return payload shape is not described, but the verdict semantics are sufficiently clear.

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

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

Schema coverage is 100%, and the description reinforces and extends the schema by embedding the exact gating formula: Promote IFF score >= min_score AND tokens <= max_tokens, with defaults 85/8000. This adds semantic weight to the parameters rather than just repeating their names.

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 states a specific action and resource: it scores .faf content, estimates tokens, and returns a promote/hold verdict, placing it clearly in Phase III pre-promotion. It distinguishes itself from siblings by combining scoring and token estimation into a deterministic 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 gives clear context by identifying this as the pre-promotion quality gate 'BEFORE it goes to a Grok Collection,' and states exact promote/hold conditions. It does not explicitly name alternative sibling tools to exclude, but the phase and threshold logic imply when this tool should be used.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds the canonical tier-table context, clarifying determinism and shared reference. It doesn't enumerate all possible symbols ('etc.'), but it states the main ones and relies on a canonical table, which is sufficient.

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 short, front-loaded sentence capturing the purpose and return type; the tier symbol list is concise. No extraneous 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?

Complete enough: has one fully documented parameter, no output schema needed because return shape is described, and annotations cover safety. The only minor gap is the unspecified full symbol list (e.g., 'etc.'), but for a fixed table this is acceptable.

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

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

Schema has 100% coverage for score (0-100). Description doesn't add range clarifications beyond this but aligns with the schema. It implies the score is numeric, but the schema description is adequate.

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?

Clear verb 'Resolve' with a specific resource ('FAF tier for a given numeric score') and describes the return value (tier symbol per canonical tier-table). No sibling overlap; indistinguishable from siblings like 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 context signals (tier-table lookup) implicitly indicate it's for mapping a score to a tier, not for complex analysis. Doesn't state exclusions versus siblings, but it's a simple deterministic resolver, and sibling names don't compete directly for this task.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavior context: the durable select preserves provenance, omitting filters yields a summary, and the tool never grades or modifies facts. This goes well beyond the annotations.

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

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

Two compact sentences, both functioning and non-duplicated. The primary action is front-loaded, and the distinguishing 'never grades' warning is placed at the end for emphasis without padding.

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 filtered query tool, the description covers what it operates on, how to filter, and what happens if filters are omitted. It is not entirely explicit about the exact shape or fields of the returned structured summary, but the core decision and invocation knowledge is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds an important cross-parameter semantic: omitting all filters produces a structured summary rather than a filtered list. It also summarizes the query axes as type/tag/priority/text, reinforcing how the optional filters work together.

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?

States a specific verb ('query') with a specific resource (the durable .fafm model) and the filter dimensions (type/tag/priority/text). It also explicitly differentiates itself from grading tools by saying it selects facts and never grades them, which is enough to distinguish it from faf_score and 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?

Provides a clear usage rule: 'Omit filters for a structured summary.' It implies this is the read/query choice for fafm content, and the 'never grades them' clause tells the agent this is not for scoring. It does not name an alternative explicitly, so it falls just short of a 5.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context: deterministic execution, WASM-pure hosted execution with no filesystem access, local execution with full FS and persisted state, and the advisory-only guarantee. This is rich, non-redundant 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 compact, front-loaded, and each sentence adds a distinct piece of information: inputs, analysis behavior, output structure, execution lanes, and advisory semantics. There is minimal redundancy with the title, schema, or annotations.

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 present, the description clearly explains the Recommendation return shape including hints, effective_policy, and partial[]. It also covers execution constraints, filesystem access differences, and the safety guarantee, so an agent has enough context to decide on and invoke the tool correctly.

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

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

Schema coverage is 100%, so the input schema already documents all five parameters and what each enables. The description adds helpful grouping around optional vs core inputs and notes how unavailable stateful signals become partial[], but it does not need to carry the documentation burden because the schema already does.

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 identifies a specific verb+resource combination: it takes raw FAF content strings and runs drift + contradiction signals across the FAF substrate, returning a structured Recommendation. It is clear about what the tool produces, but it does not explicitly differentiate it from sibling tools like faf_score, faf_gate, 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 gives clear context about when to use the tool: when raw .faf/.fafm content needs drift or contradiction analysis, and it explains both execution modes. However, it lacks an explicit 'use X instead when...' statement or a direct comparison to sibling tools.

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

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

The annotations already include readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond these: a specific Mk4 engine, a capped 0-100 output, parity with related engines, and a performance characteristic. No contradiction with annotations.

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

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

The description is short, well-structured, and front-loaded. It communicates purpose, engine, output range, parity, and performance in three sentences with 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 one-parameter tool with complete schema coverage and a description that explains the returnable range, the definition is largely sufficient. There is no output schema, but the return format is stated clearly, so an agent has enough information to invoke the tool and interpret the result.

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 covers the single content parameter fully, including details about [faf] extraction. The tool description does not need to add parameter detail. With 100% schema description coverage, a baseline of 3 is appropriate.

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

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

The description clearly states that the tool scores .faf YAML content, uses a specific engine, and returns a 0-100 capped score. This is a specific verb+resource combination. It does not explicitly distinguish itself from sibling tools like faf_validate or faf_get_tier, but its core purpose is unmistakable.

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 what the tool does but gives no guidance on when to choose it over the many sibling tools listed, such as faf_validate or faf_estimate_tokens. The parity-testing note is useful technical context, but it does not route the agent toward or away from alternatives.

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

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

Annotations establish read-only, idempotent, non-destructive behavior. The description goes beyond that by disclosing the output is exact, whole, and structure-preserving, which directly affects how an agent interprets the response. This deterministic behavior is not visible in annotations, giving the agent additional critical context.

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 dense yet efficient, packing a lot of useful information into a single sentence with dash-separated clarifications. It is not overly verbose, though the 'Phase III (FRC)' phrase may add noise without additional context.

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 annotation coverage and the schema's description of parameters, the description provides sufficient information about what is returned and how the tool behaves. The absence of an output schema is mitigated by the explicit guarantee of returning a whole .faf section. Minor ambiguity remains around FRC terminology, but it does not prevent an agent from using the 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 high, with a brief description of both content and section. The description adds real value beyond the schema by providing concrete examples of dotted paths (stack, human_context, stack.backend) and by elaborating on the omit behavior for the section parameter, which is only tersely stated in 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 states a specific action (returns) and resource (a .faf section by dotted path), and explicitly describes the result's nature (exact, whole, structure preserved). It differentiates itself from blind chunking, positioning itself as the deterministic complement.

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

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

The description clearly indicates when to use this tool: for exact, structured retrieval rather than blind chunking. It also provides a specific usage rule for the optional section parameter (omitting it lists all paths) but does not articulate explicit 'when not to use' scenarios beyond the alternative complement.

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

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

Annotations already carry the read-only, idempotent, non-destructive profile. The description adds useful behavioral detail beyond those annotations: it identifies the specific validation engine and clarifies that the tool returns a boolean threshold verdict rather than a raw score.

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 short sentences with no filler. The action, engine, and return convention are stated compactly and in a useful order.

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 one-parameter, read-only validation tool, the description provides the essential call context and defes the return condition despite no output schema. It does not mention behavior on invalid YAML or errors, but the core use case is still well covered.

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?

Scheame coverage is 100%; the only parameter is already described fine. Description restates that it validates .faf YAML content, which matches schema but adds essentially no extra semantics about input format, encoding, or edge cases.

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 action (validate .faf YAML), the execution mechanism (Mk4 Zig-WASM engine), and the success interpretation (mission-ready, >= 100). It does not explicitly contrast against siblings like faf_score or faf_analyze, but the boolean validation framing is reasonably distinctive.

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

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

The description does not say when to prefer faf_validate over related tools such as faf_score, faf_analyze, or faf_gate. There is no explicit 'use when' guidance; the agent must infer that a boolean mission-ready check is intended rather than a score or analysis.

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?

'WITHOUT cloning' is a meaningful behavioral disclosure that goes beyond the schema or annotations. 'Returns .faf content, quality score, and metadata' also provides an high-level view of side effects/results. Since readOnlyHint and idempotentHint already signal safety, the description adds extra value by clarifying the remote no-cloning behavior and the public-only constraint without contradiction.

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

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

The description is compact: three sentences cover the core action, the generation approach, and the key output items. The only 'deficit' is the phrase 'Championship-grade AI context', which is promotional rather than informative, and the slightly cryptic '6 Ws' that are not defined. Still, the definition is well front-loaded and mostly every sentence adds functional 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 a single documented parameter, solid annotations, and no output schema, the description covers the necessary ground: input source, key constraint, processing summary, and return values. It would be richer if it described the structure of the metadata or the semantics of the quality score, but it gives enough context for an agent to select and call the tool reasonably.

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 fully documents the single `repo` parameter including accepted formats, so schema_description_coverage is 100%. The description adds a publicness constraint and mentions README/package.json as analysis sources, but it does not materially enrich the semantics of the parameter beyond that; the baseline of 3 is appropriate.

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

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

The description names a specific action ('Generate a .faf file'), a clear resource ('from any public GitHub repository'), and a defining condition ('WITHOUT cloning'). It effectively sets this tool apart from the sibling faf_* tools, which target analysis, scoring, or local operations rather than repository-to-faf generation.

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

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

The description clearly implies when to use it — whenever a .faf file is needed for a public GitHub repo without cloning — but it does not explicitly ruleed out alternatives or mention when another sibling tool should be preferred. There are no exclusionary conditions, so the guidance remains implied rather than fully 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?

Annotations already disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the result is structured AI context, which is useful, but does not discuss what happens when a soul is not found or any return format details. No contradiction with annotations.

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

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

The description is only two sentences and is front-loaded with the primary action. The second sentence about structured context is useful but somewhat vague, making it earn its place without being redundant.

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 single-parameter tool with strong annotations and full schema coverage, the description is nearly sufficient. However it does not explain what a 'soul' is, provide context about the returned 'structured AI context', or mention any edge cases, while there is no output schema to fill those 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?

The schema description coverage is 100% for the single 'soul' parameter, including examples like 'spacex'. The description's 'by name' aligns with the schema's 'identifier' and adds no new semantic meaning beyond what the schema already documents, so the 100% coverage baseline 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 uses a specific verb ('Fetch'), a resource ('a context soul'), and a selection mechanism ('by name'), which clearly states the core action. It is distinguishable from the faf_* sibling tools, though the term 'soul' is never defined, preventing a perfect 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 phrase 'by name/identifier' implies that this tool is for retrieving a known soul rather than searching or discovering one, which is a legitimate implicit usage signal. However, there is no explicit guidance about when to prefer this over siblings 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?

Annotations already provide a strong safety profile: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds a modest qualifier by saying 'available,' which implies that not every soul may be returned, but it does not disclose return format, ordering, pagination, or whether all souls are scoped to the current user or workspace.

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, direct sentence: 'List all available souls.' It front-loads the verb and resource with no unnecessary words or repetition.

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 is simple with no parameters and strong annotations, so the description conveys the core operation well enough. However, there is no output schema and no information about what a 'context soul' actually is or what the returned list will contain (names, identifiers, full objects). This leaves room for an agent to mildly misunderstand the result shape.

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 zero properties, so there are no parameters to define. The description correctly focuses on the action. Baseline 4 is appropriate for a no-parameter tool.

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 verb 'List' and the resource 'all available context souls.' It conveys that this is a broad listing tool, which distinguishes it from get_soul, but it does not explicitly contrast itself with siblings like search_context or list_tags.

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

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

The description implies a use case: when you need to enumerate all available souls. However, it does not explicitly say when to choose this instead of get_soul for a specific soul, search_context for a filtered search, or list_tags for listing soul tags. With many siblings, a brief routing hint would meaningfully improve 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?

The annotations already declare the tool read-only, idempotent, and non-destructive, which removes the burden of explaining safety. The description adds some behavioral context by specifying uniqueness and counts, but it does not detail edge cases, output format, or any limitations. This is adequate given the annotation coverage but not exceptional.

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, clean sentence with no filler or repetition. It front-loads the primary action and resource while signaling the key output feature ('with counts') without adding unnecessary 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?

For a simple read-only listing tool with one well-described parameter and strong annotations, the description covers everything an agent needs: what the tool collects, from what scope, and a hint of the returned data. No output schema exists, but the nature of the result is sufficiently communicated.

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%: the only parameter 'soul' is already described as a simple identifier. The description reinforces that tags are scoped to a soul but adds no new meaning beyond what the schema already provides. The baseline of 3 is appropriate here.

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 a specific verb ('List'), resource ('all unique tags'), and scope ('used in a soul'), and even adds output nuance ('with counts'). This makes the tool's purpose unmistakable and distinguishes it from related search tools like search_by_tag.

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

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

The description implies when to use this tool — when you need a full inventory of tags for a given soul — but it does not explicitly state when not to use it or name alternatives. Siblings like search_by_tag and tag_intel provide related functionality, but no comparison is offered here.

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

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

The description discloses several behavioral traits not present in the annotations: it re-scores with the 'Mk4 Zig-WASM Enterprise scorer (33-slot)', reports drift when a baseline is given, and returns a stamped re-ground. Annotations already cover readOnly, idempotent, and non-destructive, and the description does not contradict them.

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 compact and front-loaded, with the core functionality in the first sentence and the use-case framing in the second. There is some non-essential noise, such as 'Built for Grok, by request' and repeated 'drift → reflection → re-grounded' phrasing, but overall it remains informative without being bloated.

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 three parameters and no output schema, the description still provides a fairly complete picture because the schema's verBatim description covers the output behavior. The 'drift vs baseline' and 'stamped re-ground' are sufficiently sketched for an agent to invoke the tool correctly, though terms like '33-slot' and 'Mk4 Zig-WASM Enterprise scorer' remain unexplained.

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 already provides 100% description coverage for the three parameters, including optionality of baseline and the verbatim flag's effect. The tool description adds minimal new semantic value for parameters beyond restating 'optional baseline score' and 'stamped re-ground' without clarifying parameter formats or relationships.

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 states exactly what the tool does: 're-ground on .faf content' via re-scoring, reporting drift against a baseline, and returning a stamped re-ground. It uses a specific verb (re-ground) and resource (.faf content) and further distinguishes this as 'the explicit re-grounding primitive,' separating it from siblings like faf_score, faf_analyze, and delta_check.

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

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

The description gives clear context for when to use the tool: 'for long sessions' and follows the 'drift → refresh → re-grounded' workflow. It doesn't explicitly list when not to use it or name alternative tools, but the positioning as the dedicated re-grounding primitive makes the main use case obvious.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which fully convey the safety profile. The description adds a small behavioral nuance by saying it returns 'all entries', implying the result set may contain multiple items and is scoped to a particular soul. abe No ana violation, but no additional behavioral details such as pagination or response structure. An improvement would be explicit disclosure of return format or edge 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 a single, front-loaded sentence with no extraneous information. It states the action and key objects efficiently, though it does not greedily invest the space to clarify sibling overrides or include example parameters.

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

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

Given the tool's low directionless, two required params, no output schema, and rich annotations covering read-only/idempotent behavior, the description is minimal viable. It lacks clarification of what 'entries' means, whether a tag exact-match or wildcard, and when to prefer this over sibling search tools, which leaves aobut clear gaps for an agent invoking it.

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 full descriptions for both soul and tag, so the description carries little burder for parameter semantics. The description further clarifies that the tag is used for filtering and the soul provides the scope, but it does not add format, syntax, or enum details. Baseline achieves.

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 states a specific action ('Find all entries'), a resource ('in a soul'), and a filtering mechanism ('with a specific tag'). It is clear and specific enough to distinguish the core behavior, though it does not explicitly reference sibling tools or explain how it differs from search_context, list_tags, 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 provides no guidance on when to use this tool versus alternatives. It does not name any sibling, mention exclusions, or state under what conditions an agent should prefer another search or tag-related tool. This leaves the agent to rely on sibling names alone.

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

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

Annotations already disclose read-only, idempotent, and non-destructive behavior. The description adds that only matching lines are returned and that the tool is token-efficient, which is useful context. It does not mention result limits, ordering, or behavior when many souls match, so the behavioral picture is partial.

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 short two-clause message with no filler: it identifies the operation, the resource category, and the token efficiency advantage. Every part 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?

For a simple read-only search tool, the description is nearly complete: the schema documents all parameters well, annotations cover behavior, and the description states the return granularity. Minor additional gap such as explicit result limits are not critical for successful invocation.

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

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

The input schema already describes both parameters with 100% coverage, so the description adds little new parameter-level meaning. 'Across souls' loosely maps to the optional soul parameter but does not enrich it beyond the schema's existing 'searches all if omitted' note.

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 names a specific operation (full-text search) and target resource (souls), with an explicit statement about the return format: matching lines only. It differs from tag-based searches, but it does not explicitly call out sibling tools, so it is clear though not fully differentiated.

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 'full-text search across souls' suggests this is the right tool for textual/content search, and 'token-efficient' indicates a benefit over retrieving full souls. However, the description does not explicitly say when to prefer it over search_by_tag, get_soul, or other siblings, nor 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful analytical scope but does not disclose return format, pagination, limits, or whether output differs materially when handle is omitted.

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

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

Two sentences, no fluff, with the main capability front-loaded and the optional handle use clearly stated. Every sentence contributes useful 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 that the tool has one optional parameter, no required fields, and rich read-only annotations, the description is largely sufficient for selecting and invoking it. It lacks explicit return-shape details, but that is not critical here because there is no output schema and the behavior is simple and non-destructive.

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

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

Schema description coverage is 100%, so the schema already documents the handle parameter with 'Optionally suggest tags for exact specific namepoint'. The description merely mirrors that same meaning without adding syntax, format, or behavioral constraints 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 uses specific verbs and resources: discover tag patterns, co-occurrence, candidates, and merge suggestions. It clearly differentiates from sibling tools like list_tags and search_by_tag by framing this as analytics/intel rather than a simple list or search.

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?

It clearly explains when to use the tool: to find tag patterns, co-occurrence, candidates, and merge suggestions. It also adds a conditional use case with the optional handle parameter, though it does not explicitly name excluded alternatives or say 'use list_tags when...'.

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