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 cover readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context beyond annotations by disclosing that two internal WASM calls are made, total latency is sub-millisecond, and the response includes an engine identifier. No contradiction with annotations found.

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 short, information-dense sentences. It front-loads the tool's composite nature and then gives the two details that matter most: output contents and performance characteristics. 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 the simple one-parameter schema, full schema documentation coverage, and strong safety annotations, the description covers the essential inputs, outputs, and side effects. The main gap is the lack of explicit comparison to sibling tools for when a caller should choose only faf_score, faf_get_tier, or faf_validate instead.

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' is fully described in the input schema as 'Raw .faf YAML content to analyze,' giving 100% schema coverage. The description does not add parameter-level detail, but it does not need to because the schema already carries the 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?

States a clear composite purpose: 'One-call composite — returns score, tier-ready, valid, and engine identifier.' It distinguishes itself from single-purpose siblings like faf_score, faf_get_tier, and faf_validate by making the composite nature explicit, though it does not name those siblings directly.

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 'one-call composite' phrasing implies this tool should be used when a caller wants score, tier, and validation together instead of making separate calls. However, it never explicitly states when not to use it or which alternatives to prefer for partial analysis, leaving usage primarily implied.

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?

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds meaningful extra context: sub-millisecond execution, zero allocations, and the underlying engine. This goes beyond the structured annotations and helps the agent anticipate performance characteristics.

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 earn their place: the first states the action and object, the second adds unique behavioral and use-case context. There is no filler, and the most important information appears immediately.

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 a simple single-parameter estimator, and the description covers its purpose, scope, performance, and use case. The output shape is not explicitly stated, but 'token count' strongly implies the return type. This is only a minor gap, so it is not a 5.

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 covers the single parameter with full clarity: 'Content to estimate tokens for.' The description reinforces this with 'arbitrary content' but does not add new parameter-level semantics. With 100% schema coverage, the baseline score is appropriate.

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

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

The description opens with a specific verb and resource: 'Estimate token count for arbitrary content.' This clearly distinguishes it from sibling tools like faf_analyze and faf_collections_search, which imply different operations. The mention of the Zig WASM engine further grounds the tool's identity.

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 'Useful for context-budget planning' gives the agent a clear reason to select this tool. It does not explicitly call out alternative tools or exclusions, but the focused scope plus the sibling context is sufficient for most cases.

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 mark the tool read-only and idempotent, and the description adds genuinely useful behavioral context: the verdict is deterministic, the thresholds are combined with IFF semantics, defaults are specified (85 and 8000), and the edge behavior contains a notable limitation about hold-hints not listing empty slots. This is meaningful operational detail beyond what annotations provide.

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 dense: phase label, resource, purpose, threshold rule, defaults, and edge caveat all fit into a few sentences with no filler. The most important decision logic appears early, which helps an agent parse the core behavior quickly.

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 3-parameter tool with no output schema, it provides most needed context: what to pass, the verdict rule, defaults, and an edge-behavior warning. However, the exact return shape is not described beyond 'promote/hold verdict,' and the term 'hold-hint' remains slightly under-specified without a schema or further explanation.

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 all three parameters, and the description enriches that by adding default values and the exact condition under which a promote verdict is decided. It does not expand each parameter individually, but with full schema coverage the additional semantics are enough to invoke the tool correctly.

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 resource (.faf content), what the tool does (scores it, estimates tokens, and returns a promote/hold verdict), and where it sits in the pipeline (pre-promotion quality gate before a Grok Collection). The combined scoring-and-gating role differentiates it from siblings like faf_score and faf_estimate_tokens, even without naming them explicitly.

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 a clear usage context and trigger: invoke this before content goes to a Grok Collection, with promotion contingent on both thresholds. It does not explicitly name alternatives to use instead when only scoring or only token estimation is needed, so it lacks explicit exclusions but the context is clear.

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 this read-only, idempotent, and non-destructive, and the description adds genuinely valuable behavioral context: hosted execution is WASM-pure with no filesystem access, local execution has full FS and persisted state, and the tool is advisory-only and never auto-fires. This clearly exceeds what the annotations alone provide.

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?

Every sentence in the description carries useful information: core behavior, output shape, execution-lane constraints, stateful-signal caveats, and safety semantics. It is dense but not bloated, and the most decision-relevant information is front-loaded.

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

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

With no output schema available, the description compensates by defining the Recommendation shape and the hints fields. It also covers execution environments, state availability, and safety posture, making this definition sufficiently complete for an agent to understand the tool's contract.

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 input schema already documents each parameter meaningfully. The description lists the accepted file types and frames them as inputs to drift/contradiction analysis, but it does not add substantial parameter behavior 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 states a clear verb-resource relationship: it takes raw content strings, runs deterministic drift/contradiction signals, and returns a structured Recommendation. It is clearly legible and unlikely to be confused with a vague system tool, though it does not explicitly distinguish itself from closely related siblings like faf_analyze or faf_gate.

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

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

The description implies when to use the tool by describing its orchestrated recommendation role and advisory nature, but it never explicitly says when to prefer this over alternatives. With 19 sibling tools, the absence of direct sibling positioning leaves the agent to infer the right 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?

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 set readOnlyHint=true, idempotentHint=true, destructiveHint=false, lower the bar. The description adds genuine context: it names the underlying engine (Mk4 Zig-WASM) and, critically, defines the success threshold ('true if mission-ready >= 100'), which tells the agent what a positive result means. It stops short of describing failure mode on malformed YAML (throw vs. false), but the added value is meaningful.

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, zero redundancy. The first sentence states the operation and engine; the second states the return semantics with the exact threshold. 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?

For a single-parameter, read-only, idempotent tool with a well-described return condition, this is nearly complete. The only gap is the failure mode for syntactically invalid YAML when the engine score is undefined. An agent can call and interpret results correctly with what's given.

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 schema fully describes 'content' as the raw .faf YAML content. The description reinforces that it's YAML and adds the engine/threshold context, but adds no per-parameter semantics beyond that. Baseline 3 applies.

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

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

States a specific verb ('validate') with a specific resource ('.faf YAML content') and clarifies the engine used. It adds meaning by defining what 'valid' means — mission-ready, score >= 100 — which goes beyond the tool name and title. It doesn't explicitly contrast with sibling tools like faf_analyze, so it's not fully demarcated.

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 validation over analysis (faf_analyze), delta checks, or the various search/query siblings. The description tells how the tool behaves but gives the agent no explicit selection criteria, and no mention of 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, openWorldHint, idempotentHint, and false destructiveHint. The description adds meaningful behavioral context beyond those hints: it does not clone, it extracts data from README, languages, and package.json, it generates a Championship-grade AI context, and it returns content plus quality score and metadata. No contradiction with the annotation 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 compact at three sentences and front-loaded with the primary action. The only mild weakness is 'Championship-grade AI context', a promotional phrase that adds no precise behavioral meaning, but the overall density remains high and it does cover the key data points.

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 tool with a single parameter, no output schema, and relevant annotations, the description covers the prerequisites, the input form, the processing behavior, and the return fields (.faf content, quality score, metadata). It does not discuss error cases or network dependencies, but those are nonessential given the scope.

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

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

The schema already describes the repo parameter completely with format examples. The description supplements this by clarifying that the repository must be public—important operational constraints that would not be obvious from the schema alone. That lifts it above the baseline for 100% schema coverage.

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

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

The description states a specific verb ('Generate'), a specific resource ('.faf file from any public GitHub repository'), and a distinguishing constraint ('WITHOUT cloning'). It tells the agent exactly what the tool produces, making it easy to separate from analysis, scoring, and validation 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?

The description implies the main scenario: create a .faf file from a public GitHub repo without cloning. However, it does not explicitly say when to choose this tool over siblings like faf_analyze, faf_validate, or generate_faf_from_github, nor does it provide exclusions or alternative routing.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already convey that this is a safe, non-mutating read-only operation. The description adds no additional behavioral context beyond saying it lists, and it does not mention whether results are ordered, paged, limited, or filtered. With annotations covering the safety profile, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence: 'List all available context souls.' It states the verb and resource concisely with zero wasted words, which achieves appropriate size and clarity for a zero-parameter list tool.

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

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

For a zero-parameter, read-only tool with a trivial schema, the description nearly suffices. The only omission is clarifying what a 'context soul' is and how many of them might be returned, but given the tool's simplicity and the safety annotations, the definition is fairly complete.

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

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

The tool has zero parameters, and Baselines we set the baseline for a 0-parameter tool at 4. Although the description adds no parameter-specific semantics, the absence of parameters means there is nothing meaningful to document and the 100% schema description coverage (or equivalent) means nothing remains undocumented. This deserves the baseline 4 rather than a high parameter-related score since the description itself offers no parameter detail.

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 says 'List all available context souls' which names a specific verb and resource, so it is clear about what the tool does. However, it does not distinguish this from sibling tools like list_tags or get_soul beyond the resource name, and 'context souls' is somewhat domain-specific jargon that may not be immediately informative without additional 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 provides no guidance on when to use this tool versus siblings such as get_soul, list_tags, search_by_tag, or generate_faf_from_github. There is no mention of what 'context souls' means, nor any context indicating whether this is a discovery tool, a navigation tool, or a retrieval tool. An agent would have to infer usage from the tool name and schema 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?

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?

With annotations already covering read-only, idempotent, and non-destructive behavior, the description adds useful context: re-scoring via the Mk4 scorer, honoring the authored app-type shape, optional drift delta, and stamped vs verbatim output. It could be clearer about exactly what the 'stamp' contains, but the annotations do not carry that burden.

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 first sentence is dense and informative, but the second sentence partly repeats the title and process, and the final 'Built for Grok, by request' adds no operational value. The description remains compact but not every sentence earns its place.

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

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

Given no output schema, the description sufficiently sketches the shape for both default verbatim and non-verbatim mode: stamped delta+summary vs full content verbatim plus stamp. It supports agent deciscion-making on when to call it in long sessions, and the schema and annotations cover the remaining invocation details.

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 parameter descriptions are already clear about content, baseline drift, and verbatim mode. The tool description mostly rephrases those concepts without adding deeper semantics, which is acceptable at the baseline for fully documented schemas.

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 operation: re-ground on .faf content, re-score via a named scorer, report drift against baseline, return a stamped re-ground. The 'explicit re-grounding primitive for long sessions' differentiates it from a plain first-time scoring tool and from the sibling search/analysis 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?

Gives a clear 'when' — any long session where drift needs to be reset via refresh/re-ground. It does not name alternative tools or say when not to use it, so it stops short of explicit when-not/alternatives guidance.

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

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

Annotations already communicate that the tool is a read-only, idempotent, non-destructive operation, so the description does not need to cover those safety aspects. It adds only a minor behavioral detail: the result set includes 'all entries'. It does not describe pagination, result ordering, potential error conditions, or output format. Since annotations carry the main behavioral burden, a mid-range score is appropriate.

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

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

The description is a single, well-formed, front-loaded sentence with no unnecessary text, filler, or repetition. Every word contributes meaning: action, scope, resource, and parameter. It is concise while remaining clear.

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

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

For a simple two-parameter read-only tool with strong annotations, the description is close to complete. It clarifies the target of the search and the namespace ('soul'), and the input schema fills the details. The main gap is that it does not specify what an 'entry' looks like in the response or how results are formatted; since there is no output schema, slightly more context about the return shape would have been helpful. Overall it is adequate but not exhaustive.

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

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

The schema already describes both 'soul' and 'tag' (100% known coverage), so the description does not need to re-explain them. The description adds no further detail about default values, enum constraints, format requirements, or edge-case behaviors. This matches the baseline of 3 for a fully documented 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 a clear verb and resource combination: 'Find all entries in a soul with a specific tag.' It identifies the main input (soul and tag) and the goal, and it is not a tautology of the tool name. It does not explicitly differentiate from sibling tools, but the wording is specific enough for an agent to infer the tool's job.

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 its intended use: when you need to find entries with a specific tag in a soul. However, it gives no explicit guidance on when not to use it, nor does it mention alternatives like search_context or list_tags. The 'when to use' information is indirect rather than explicit.

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

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

Annotations already mark the operation read-only, idempotent, and non-destructive, and the description is consistent with that. It adds useful behavior beyond annotations by revealing that results are line-only and token-efficient.

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 carry all the essential information, with the primary action front-loaded. Every phrase earns its place, and there is no redundant or filler content.

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

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

The schema, annotations, and description together provide a solid operational picture: what is searched, what is returned, and that the operation is safe. Minor details such as pagination, result limits, or case sensitivity are absent, but they are optional rather than critical.

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

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

The input schema already describes both parameters thoroughly, with 100% coverage. The tool description does not add new parameter-level semantics, so it stays at the schema-driven baseline.

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 opens with 'Full-text search across souls', a specific verb and resource that is instantly clear. The next sentence, 'Returns matching lines only', distinguishes it from sibling tools like search_by_tag or get_soul by declaring its result shape.

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 establishes a clear use case: full-text content search across souls, with a token-efficient return option. It does not explicitly name alternatives or say when not to use it, but the context is specific enough for an agent to infer the intended invocation scenarios.

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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already cover the safety profile. The description adds behavioral context about the tag discovery and suggestion capabilities, but does not disclose details like return format, volume of results, or any additional side effects.

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

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

The description is concise, front-loads the primary purpose (tag pattern discovery), and quickly mentions the additional suggestion feature. It uses an efficient two-clause structure with no redundant or overly verbose 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?

For a tool with one optional parameter, no output schema, and annotations that define the safety profile, the description is mostly complete. The main gap is it does not specify the output format or how results are returned, such as whether suggestions include confidence scores or structured data.

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 parameter schema covers the handle parameter with a description, achieving 100% schema description coverage. The tool description mentions optional tag suggestions for a specific handle, which supplements the schema. However, it does not add deeper meaning beyond the schema's own 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 purpose: discovering tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints. It also mentions an optional behavior (suggesting tags for a specific handle), which adds another clear capability.

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 the tool—when tag-related analysis or suggestions are needed—and the optional handle parameter provides context for a specific use case. However, it does not explicitly state when NOT to use this tool or mention alternatives.

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