Persistent Project Context for xAI Grok

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

The description lacks any behavioral disclosure beyond the core purpose. Terms like 'soul' are undefined, and there is no mention of side effects, data mutability, authentication needs, or rate limits. Since no annotations exist, the description bears full responsibility but fails to provide necessary 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 a single sentence that efficiently states the tool's purpose. It is not verbose, but it could be slightly more informative without sacrificing conciseness.

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

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

Given the lack of an output schema and annotations, the description should explain what the tool returns (likely one of three strings) and clarify domain-specific jargon (e.g., 'soul'). It is incomplete for helping an agent correctly interpret the tool's behavior.

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 parameter 'topic' is adequately described in the schema. The description adds no additional meaning beyond what the schema provides, so it meets the baseline of 3 for high 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 uses a specific verb 'Determine' and identifies the resource 'topic' and three possible outcomes (FULL, DELTA, X-DELTA soul). This clearly distinguishes it from sibling tools like get_soul or list_souls, which retrieve or list souls rather than classifying a topic.

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

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

No guidance is provided on when to use this tool vs. alternatives such as faf_analyze or faf_score. The description does not mention prerequisites, context, or when not to use it, leaving the agent without decision support.

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

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

No annotations are provided, so the description must carry full behavioral disclosure. It mentions two WASM calls and sub-millisecond performance but does not disclose side effects, error behavior, or permission requirements. This is insufficient given the lack of 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 extremely concise with two sentences, no redundant information, and the key purpose and value proposition are front-loaded.

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

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

The description mentions what the tool returns (score, tier-ready, valid, engine identifier) but does not specify the output format or structure. Since there is no output schema, the description should be more explicit about the return representation to ensure correct usage.

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

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

Schema description coverage is 100% for the single parameter, and the attribute description in the schema ('Raw .faf YAML content to analyze.') is clear. The tool description adds no further semantic value beyond what the schema provides, warranting a baseline score of 3.

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

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

The description clearly states it is a composite tool that returns score, tier-ready, valid, and engine identifier. It distinguishes itself from sibling tools like faf_score, faf_validate, and faf_get_tier by offering a one-call alternative.

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 this tool replaces separate calls to faf_score, faf_validate, and faf_get_tier, but does not explicitly state when to use it versus alternatives. It provides performance info but lacks explicit when-to-use/when-not-to-use guidance.

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

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

With no annotations, description carries full burden. Discloses caching behavior (KV-cached with 1h TTL), output structure (content, score, file), and environment handling. Does not contradict any annotation.

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?

Relatively concise but front-loaded with jargon ('Phase III', 'FRC §7b') that may not be universally understood. Structure is somewhat fragmented across two sentences and a phrase.

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

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

Given no output schema, description adequately explains return values (chunks with content, score, file) and essential context like caching, secret requirement, and hybrid retrieval partner. Provides sufficient completeness for a search tool.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds no extra parameter-specific meaning beyond schema, but provides overall context about output and caching. Baseline 3 is appropriate.

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

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

Clearly states it performs semantic search over a Grok Collection and returns matched chunks, differentiating from siblings by mentioning composition with faf_section for hybrid retrieval. However, includes extraneous implementation details like 'Phase III' and 'KV-cached' that could confuse agents.

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 context on prerequisites (requires XAI_API_KEY) and suggests composing with faf_section, but lacks explicit when-to-use/when-not-to-use guidance or alternatives. Usage is implied but not fully delineated.

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

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

No annotations are provided, so the description carries full burden. It adds behavioral traits beyond the basic function: 'Sub-millisecond, zero allocations' indicates high performance and no memory allocation side effects. This is valuable context for an agent. Does not contradict annotations (none 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 concise with three sentences: first states purpose and engine, second states performance, third states use case. No unnecessary words. Front-loaded with the core action. Every sentence adds value.

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

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

Given the tool's low complexity (single parameter, no output schema, no annotations), the description is complete. It covers purpose, method, performance, and applicability. No gaps remain for an agent to understand when and how to use 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 input schema has 100% coverage with the single 'content' parameter described as 'Content to estimate tokens for.' The description supplements this by specifying 'arbitrary content,' implying the tool accepts any text, not just specific formats. This adds meaning beyond the schema.

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

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

The description clearly states the tool estimates token count for arbitrary content using a specific engine (Zig WASM). The verb 'estimate' and resource 'token count' are precise. It distinguishes from siblings like faf_analyze or faf_score which perform different tasks, as token estimation is unique among the listed siblings.

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 a clear use case: 'Useful for context-budget planning.' This implies when to use the tool. It does not explicitly mention when not to use it or compare with alternatives, but given the sibling list, no other tool directly competes for token estimation. Adequate guidance.

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

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

No annotations are provided, so the description carries the full burden. It states the tool is 'deterministic' and mentions edge parity and the 'hold-hint can't list empty slots'. However, it does not explicitly confirm that it is read-only, nor does it cover side effects, permissions, or error handling. The omission of read-only behavior is a gap.

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

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

The description is concise (3 sentences) and front-loaded with the purpose. Every sentence provides necessary information: context (Phase III), function (scores+estimates+verdict), decision rule + defaults, and a note on edge behavior. No redundant text.

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

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

Given the absence of an output schema, the description should specify the return format (e.g., 'promote' or 'hold' string). It only says 'returns a deterministic promote/hold verdict' without details on structure or possible values. Also missing error cases or preconditions. Otherwise, the tool's behavior is 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?

The description adds value beyond the input schema by stating the promote condition ('Promote IFF score >= min_score AND tokens <= max_tokens') and providing defaults (85/8000). It also adds operational context like 'Edge parity with the local gate'. The schema already covers parameter descriptions, so the description enriches semantics.

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 is a 'pre-promotion quality gate' that 'scores .faf content' and 'returns a deterministic promote/hold verdict'. It specifies the Phase III (FRC) context and differentiates from siblings like faf_score (scores only) and faf_estimate_tokens (tokens only) by combining both and providing a decision.

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

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

The description explains when to promote ('IFF score >= min_score AND tokens <= max_tokens') and gives defaults (85/8000). It implies use before a Grok Collection and mentions 'edge parity with the local gate'. However, it does not explicitly compare with alternative tools like faf_score + faf_estimate_tokens or specify when not to use it.

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

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

No annotations are provided, so the description carries full burden. It mentions the output format but does not disclose what happens for invalid inputs (e.g., score out of 0-100 range) or whether the tool has side effects. The reference to 'canonical tier-table' is vague.

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

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

The description is a single, efficient sentence that front-loads the action. It is concise with no wasted words, though it could benefit from slightly more structure (e.g., separating input and output clearly).

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

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

Given the tool's simplicity (single parameter, clear output), the description is fairly complete. It states the purpose and return value. However, it lacks details about error handling or the tier-table definition, which would improve completeness.

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

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

The schema describes the 'score' parameter as 'Numeric score 0-100' with 100% coverage. The description adds no additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool resolves a FAF tier for a numeric score and returns a tier symbol. The verb 'resolve' and resource 'tier for a score' are specific, and the tool is distinct from siblings like faf_score (which computes a score) or faf_analyze (which analyzes content).

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

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

No guidance on when to use this tool versus alternatives (e.g., after scoring, or as part of a pipeline). The description does not mention prerequisites or exclusions, leaving the agent to infer context from the tool name.

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

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

No annotations provided, so description carries full burden. It discloses the tool is read-only ('SELECTS facts', 'never grades them') and preserves provenance. It does not detail side effects, rate limits, or auth needs, but for a query tool the key behavior is disclosed.

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

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

The description is very concise: three sentences with no wasted words. It front-loads the core action and follows with key behavioral traits. Every sentence adds value.

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

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

No output schema exists, yet the description only mentions 'structured summary' without detailing the return format, pagination, or error handling. For a 5-parameter tool with no annotations, the description is somewhat bare, though it covers core functionality.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal additional meaning beyond listing filter types, though it provides usage context ('omit filters for summary'). No new parameter semantics or format details are added beyond the schema.

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

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

The description clearly states the tool queries the durable .fafm model by type/tag/priority/text, with an option to omit filters for a structured summary. It explicitly distinguishes from siblings like faf_score by noting it does not grade facts, preserving provenance.

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

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

The description provides usage guidance: query by specific filters and omit for a summary. It implies this is for selection only (not scoring) but lacks explicit when-not or alternative recommendations. The context is clear but not exhaustive.

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

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

With no annotations, description carries full burden. It discloses deterministic behavior, drift+contradiction analysis, execution modes, and advisory-only policy. However, it does not mention side effects, state modification, or authentication needs. The 'persisted state' reference for heavy-lane is vague.

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

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

Description is concise at around 150 words across 4 sentences, front-loaded with purpose. Uses clear structure with details on execution modes and return value. No wasted words.

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

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

Given no output schema, description adequately explains return structure (Recommendation with fields) and execution context. Covers parameter roles. However, missing details on error handling or behavior when inputs are incomplete.

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

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

Schema coverage is 100% and description adds context beyond schema by explaining what each parameter enables (e.g., 'Enables drift detection' for fafm). It also notes that faf is required for meaningful analysis, which aids the agent.

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

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

Description clearly states it takes raw content strings and runs deterministic drift+contradiction signals, returning a structured Recommendation. It is specific about the resource (FAF substrate) and action. However, it does not explicitly differentiate from sibling tools like faf_validate or faf_analyze, though the combined drift+contradiction aspect is 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?

Description explains execution modes (light vs heavy lane) and advisory nature, but lacks explicit guidance on when to use this tool versus alternatives such as faf_validate or delta_check. It implies usage for comprehensive analysis but does not state exclusions or prerequisites.

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

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

With no annotations, the description adds some behavioral context by mentioning the engine ('Mk4 Zig-WASM'), parity testing, and sub-ms speed. However, it does not disclose whether the tool is read-only, has side effects, or requires authorization, leaving significant gaps.

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

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

The description is three sentences, each serving a purpose: action, output/engine, and speed. It is concise, front-loaded, and contains no filler. 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 the tool's simplicity (1 param, no output schema), the description covers essential aspects but lacks interpretation of the score (e.g., what 0 vs 100 means) and any validation notes. It is adequate but not fully complete for an agent to make informed decisions.

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 'content' parameter as 'Raw .faf YAML content' (100% coverage). The description adds valuable semantics by explaining automatic extraction of [faf] sections, which goes beyond the schema and helps the agent understand input handling.

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 action ('Score .faf content') and resource ('.faf YAML content') and specifies the output range (0-100 capped), making the purpose unambiguous. While it doesn't explicitly distinguish from siblings, the verb 'score' implies a narrower function compared to 'analyze' or 'validate'.

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

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

The description provides no guidance on when to use this tool versus alternative siblings like faf_validate or faf_analyze. It lacks any context about prerequisites, limitations, or scenarios where this tool is preferable.

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

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

No annotations are provided, so the description carries full burden. It states the tool returns exact whole sections with structure preserved, but does not disclose any behavioral traits such as side effects, authentication needs, rate limits, or error behavior. Minimal transparency beyond the basic functionality.

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

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

The description is a single sentence that efficiently conveys the core purpose and a key usage nuance. It is front-loaded with the main action. Could be slightly more structured, but no unnecessary 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 2 parameters, no output schema, and no annotations, the description covers the essential behavior: retrieving exact sections and listing all paths. It lacks details on error handling and dotted path format, but for a simple retrieval tool it is mostly complete.

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

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

The description adds meaning beyond the input schema by explaining the effect of omitting the 'section' parameter (lists all paths). With 100% schema coverage, the baseline is 3, and the description elevates it by clarifying optional behavior.

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

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

The description clearly states it returns an exact, whole .faf section by dotted path, and mentions listing all paths when section is omitted. It provides a specific verb ('returns') and resource ('.faf section'). However, it does not explicitly distinguish from sibling tools beyond a vague reference to 'blind chunking'.

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 one usage pattern (omit 'section' to list paths) but lacks explicit guidance on when to use this tool versus alternatives. It mentions 'deterministic complement to blind chunking' but no further comparisons or exclusions.

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

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

No annotations provided, so description carries full burden. It mentions the engine and return condition, but does not disclose error handling, side effects, or validation strictness.

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

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

Two concise sentences with no superfluous information. Every sentence adds value.

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

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

For a simple single-parameter tool with no output schema, the description captures essential behavior but lacks error scenarios and validation criteria.

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 schema already defines the 'content' parameter. Description adds minimal context ('Raw .faf YAML content'), not significantly beyond schema.

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

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

Description clearly states the tool validates .faf YAML content via a specific engine and specifies the success condition (mission-ready >= 100). This distinguishes it from siblings like faf_analyze and faf_score.

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

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

No explicit guidance on when to use this tool versus alternatives like faf_analyze or delta_check. It implies a simple validation check but does not exclude other use 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?

With no annotations, the description bears full burden. It discloses the core behavior (no cloning, extraction, analysis) but omits potential side effects, authentication requirements, or error conditions. The description is descriptive but not fully transparent about external API calls or data handling.

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 long, front-loaded with the key action, and wastes no words. Every sentence adds value: first states the primary operation, second details what is extracted and returned.

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 interface (1 required parameter, no output schema, no annotations), the description adequately covers the tool's input, process, and outputs. It mentions return fields (content, quality score, metadata) and key extraction details. However, it lacks information on error handling or state assumptions (e.g., internet access), which would push it to 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?

Schema coverage is 100%, and the schema already specifies the parameter (repo) with examples. The description adds context about how the repo is used (extracting from README, languages, package.json), but does not enhance parameter-level semantics beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a .faf file from a public GitHub repository without cloning. It specifies the key actions (extracting 6 Ws, analyzing stack) and outputs (.faf content, quality score, metadata). This distinguishes it from sibling tools like faf_analyze or faf_score.

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

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

While the description implies when to use (when you need a .faf file from a GitHub repo), it fails to provide explicit guidance on when not to use or mention alternatives among the 14 sibling tools. No exclusions or prerequisites are stated, leaving agents to infer usage.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It mentions returning 'structured AI context' but omits details on side effects, authentication requirements, error behavior, or idempotency, which are critical for a fetch operation.

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

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

The description is extremely concise (one sentence) and front-loaded with the core purpose. However, it may be too brief, sacrificing valuable context for brevity.

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

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

For a simple fetch tool with no output schema and no annotations, the description does not adequately explain the return structure, error handling, or what constitutes a 'context soul.' This leaves the agent with insufficient information to fully handle the response.

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

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

The input schema has 100% coverage with a description for the 'soul' parameter including examples. The description adds minimal value beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool fetches a context soul by name and returns structured AI context. The verb 'fetch' and resource 'context soul' are specific, and it distinguishes itself from sibling tools like list_souls or search_context by its direct retrieval by name.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_souls (to list all souls) or search_context (to search). It lacks explicit when-not-to-use or alternative references.

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 simply states the operation. It does not explicitly declare read-only behavior, but it is implied by 'list'. Without annotations, the description could be more explicit about safety or side effects, but it is not misleading.

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

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

The description is a single, clear sentence with no unnecessary words. It is perfectly concise.

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

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

For a tool with no parameters and no output schema, the description provides the basic purpose. However, it does not explain what a 'context soul' is or what the output contains (e.g., list of names vs. objects). It is minimally 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?

There are zero parameters, and the schema coverage is trivially 100%. The description adds no parameter information, but baseline for 0 parameters is 4.

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 the specific verb 'list' and resource 'souls', clearly indicating it returns a collection. This distinguishes it from 'get_soul' (singular) and 'list_tags' (different resource).

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

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

No guidance is provided on when to use this tool versus alternatives like 'get_soul' for a specific soul or search tools. The description does not mention exclusions or prerequisites.

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

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

No annotations are provided, so the description carries full burden. It states the tool lists tags with counts, implying a read-only operation. However, it does not disclose potential side effects, error handling (e.g., invalid soul), or ordering of results. The behavioral disclosure is minimal but adequate for a simple listing tool.

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

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

The description is a single, concise sentence that front-loads the core purpose. Every word is necessary, and there is no redundant or irrelevant 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 the tool's simplicity (one parameter, no output schema), the description is mostly complete. It explains what is listed (unique tags) and that counts are included. However, it could mention ordering (e.g., alphabetical) or behavior when the soul has no tags, which would make it fully 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 input schema already describes the 'soul' parameter as 'Soul identifier', with 100% coverage. The description adds no extra meaning beyond the schema's type and description. Baseline 3 is appropriate as the description does not enhance parameter understanding.

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

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

The description clearly states the tool lists all unique tags in a soul with counts. The verb 'list', resource 'tags', and scope 'used in a soul' are specific, distinguishing it from sibling tools like search_by_tag (which finds souls by tag) and tag_intel (which analyzes tags).

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

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

No guidance on when to use this tool versus alternatives like search_by_tag or tag_intel. The description implies usage for viewing tags of a specific soul, but does not mention exclusions, prerequisites (e.g., soul existence), or alternative tools for different use 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?

With no annotations, the description carries the full burden. It explains the re-scoring process (Mk4 Zig-WASM scorer, 33-slot) and the optional baseline drift. However, it does not disclose whether the tool has side effects, requires authentication, or has any rate limits, leaving some behavioral ambiguity.

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

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

The description is concise: two sentences that efficiently convey the core operation and usage scenario. Every sentence adds value with no redundancy. Excellent structure.

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?

Considering no output schema and no annotations, the description covers the main aspects: what it does, key parameters, and the overall process. It could be improved by briefly stating the return format explicitly, but overall it is adequately complete for an agent to understand and use 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 description coverage is 100%, so the baseline is 3. The description adds little beyond the schema definitions, mainly restating the purpose of 'content' and 'baseline' without additional detail. No extra value for parameter semantics.

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

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

The description clearly states the tool's purpose: re-ground on .faf content by re-scoring and reporting drift. However, it does not explicitly differentiate from sibling tools like faf_score or faf_validate, which could cause confusion about when to use this specific tool.

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

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

The description mentions it is the 'explicit re-grounding primitive for long sessions: drift → refresh → re-grounded,' implying use after drift in long sessions. However, it provides no explicit guidance on when not to use it or alternatives, leaving the agent to infer from sibling names.

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

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

No annotations provided, so the description bears full responsibility. It does not disclose whether the operation is read-only, if permission checks are needed, or what happens on failure (e.g., no matching tags). The description only restates the tool's basic function without behavioral 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 a single concise sentence with no redundant information. Every word is necessary for conveying the primary purpose.

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

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

The description lacks details about return values, pagination, or error handling. For a search tool without an output schema, the description should clarify what 'entries' means and the response format, which it fails to do.

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

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

Input schema coverage is 100% with descriptions for both parameters. The tool description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not enhance understanding of parameter usage or formats.

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

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

The description clearly states the action (find) and resource (entries in a soul with a specific tag), making the tool's purpose obvious. However, it does not distinguish from sibling tools like search_context, which could be confusing.

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

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

No guidance on when to use this tool versus alternatives such as search_context or list_tags. The description does not specify prerequisites or scenarios where this tool is preferred.

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

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

With no annotations, the description adds behavioral context: returns matching lines only (token-efficient), implying a read-only operation with partial content. However, it doesn't mention auth needs, rate limits, or other 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?

Extremely concise: one sentence that front-loads the main action and key behavioral trait ('token-efficient'). Every word adds value, no redundancy.

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

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

For a simple tool with two parameters and no output schema, the description is adequate but could be more complete. It lacks details on result format (e.g., how many lines, truncation), pagination, or performance implications.

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?

Both parameters are already well-described in the input schema (100% coverage). The description adds no new semantic information beyond what the schema provides, so baseline of 3.

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

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

Clearly states 'Full-text search across souls' with a specific verb and resource. The added detail 'Returns matching lines only (token-efficient)' helps distinguish from sibling tools like 'search_by_tag' or 'list_souls', but no explicit sibling differentiation.

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

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

No guidance on when to use this tool versus alternatives like 'search_by_tag' or when not to use it. Lacks context on prerequisites or typical use 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?

With no annotations, the description carries full burden for behavioral disclosure. It implies a read operation but does not detail side effects, permissions, rate limits, or what 'patterns' and 'suggestions' specifically entail. The scope 'across all namepoints' is mentioned, but deeper behavioral traits are missing.

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

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

The description is two sentences, front-loaded with the main action, and contains no unnecessary words. Every sentence adds value: the first lists capabilities, the second specifies the optional parameter.

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

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

Given no output schema and no annotations, the description should explain return values or behavior. It only says 'discover' and 'suggest' without describing the output format or how it differs from similar tools like list_tags. This leaves the agent with incomplete information for safe 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?

Schema description coverage is 100% with one optional parameter 'handle' described. The description adds the phrase 'optionally suggest tags for a specific namepoint' which aligns with the schema but adds no additional syntax or format details. Baseline 3 is appropriate as schema already covers the parameter.

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

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

The description clearly states it discovers tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints, with an optional handle for specific suggestions. It distinguishes from sibling tools like list_tags (simple listing) and search_by_tag (searching) by focusing on analytical insights.

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 some guidance by mentioning the optional handle parameter for specific namepoint suggestions, but it does not explicitly state when to use this tool versus alternatives like list_tags or faf_analyze. No exclusions or context about prerequisites are given.

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