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

Annotations already mark it read-only and closed-world, but the description adds valuable behavioral context: the exact return object keys and that no orchestrator execution or side effects occur. It stops short of documenting error or fallback behavior, so a 4 rather than 5.

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

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

Three dense sentences, front-loaded with the key distinction and return shape. Every clause adds scope or output information, with no filler.

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 supplies the return shape and the tool's read-only, non-executing nature. Annotations cover safety and the schema covers the single parameter, so the definition is complete enough for an agent to call correctly.

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

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

There is one optional path parameter, and schema description coverage is 100%, so the schema already fully documents it. The description does not mention the path parameter or add syntax beyond what the schema provides, so the 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 ('Introspect') and resource ('effective orchestration policy'), and explicitly positions itself against sibling faf_orchestrate_recommendation by saying it does not run the orchestrator. An agent can tell what it does and how it differs from the alternative without opening schemas.

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?

Says when to use it (to see what the next faf_orchestrate_recommendation call would use without running it) and what it excludes (no drift detection, no signals, no receipt). It names the sibling relationship directly, leaving no ambiguity about the alternative.

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

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

Annotations already indicate destructive behavior (destructiveHint=true). The description adds context: writes file to target directory (created if missing), refuses overwrite unless force set, and returns confirmation. No contradictions 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?

Three well-structured sentences, front-loaded with purpose. No wasted words; every sentence adds necessary 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?

Covers key aspects: file creation, overwrite behavior, directory creation, return value, and next step (call faf_score). Despite no output schema, the return value is described. For a tool of this complexity, it is complete.

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

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the force parameter's effect (override refusal) and implying the directory parameter's role (target for writing). This goes beyond schema descriptions.

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

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

The description clearly states it creates a project.faf file (IANA-registered context file) with specific purpose (persistent project DNA). It distinguishes from sibling tools like faf_score (readiness check) and faf_sync by detailing its unique role and output.

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?

Explicitly says 'Run once at project start, or with `force` to regenerate, then call faf_score to check readiness.' It also notes the refusal to overwrite without force. However, it does not directly compare with all siblings like refresh_faf, but the intended use case 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?

Adds real behavioral context beyond the annotations: it writes a recommendation receipt on every call (explaining why readOnlyHint=false is correct for a tool that is otherwise 'read-only WRT substrate state'), and it is explicitly advisory and non-destructive. It does not disclose latency, cost, or failure modes.

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

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

Front-loads the core purpose and the advisory constraint, and every clause carries information. It is dense with domain jargon ('substrate', 'take-a-hint'), which slightly reduces scannability but does not waste sentences.

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 complex, no-parameter orchestrator with no output schema, the description adequately conveys both the inputs (implicitly the current substrate state) and the shape of the returned recommendation. Return-value detail is generic rather than schema-precise, but the description covers what an agent needs to decide to call 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The description correctly implies no caller inputs are needed, only current substrate state.

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 and resource ('returns a structured recommendation about drift') and enumerates the payload (which refresh, why, severity, signals). It is clearly distinguishable from the sibling refresh_* tools, which actually perform refreshes, since this only recommends.

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?

Establishes clear context: it is the 'heavy orchestrator' that composes drift detection, contradiction check, repeat-offender, take-a-hint and refresh history, and it is ADVISORY ONLY and never auto-fires. It does not, however, explicitly route the agent against alternatives like faf_get_orchestration_policy or refresh_faf.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured behavioral facts: the operation is deterministic (same .faf always scores the same) and it returns score, tier, and per-slot breakdown. It does not mention auth/permission needs or rate limits, but the determinism disclosure is valuable added 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?

Three tight sentences, front-loaded with the verb and scoring basis. The 'how much project DNA an agent has before it has to guess' metaphor follows the already-explicit '33-slot context model' and is mildly redundant, but every other clause carries real 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?

With no output schema, the description correctly compensates by naming the return values (score, tier, per-slot breakdown), and the single optional param is fully schema-documented. The main gap is that it never states which project or .faf artifact is scored, which is non-obvious for a zero-required-param 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?

Only one optional boolean parameter and schema description coverage is 100%, so the schema already documents 'details' fully; the baseline is 3. The description references a 'per-slot breakdown' return, which loosely maps to details=true, but adds no explicit semantics for the parameter itself.

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 (score) and resource (project AI-readiness) with a named, concrete scoring basis: the fixed 33-slot context model and a 0–100% range. This is clearly distinguishable from siblings like faf_trust and refresh_faf, which imply different operations.

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?

Usage is only implied: an agent can infer it is for assessing readiness, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as faf_trust (which presumably evaluates a related quality dimension). No prerequisites or calling context are given.

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 idempotentHint=true and destructiveHint=false, so the safety baseline is covered. The description adds real value beyond that by specifying the mechanism (inject a structured .faf block at the top) and the side effect boundary (prose below is preserved), which tells the agent exactly what gets modified. It stops short of saying whether missing context files are created.

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

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

Three short sentences, front-loaded with the action and its targets, then the safety guarantee, then the rationale. The closing line ('One source of truth, every tool kept current') is slightly promotional but does convey the maintenance intent.

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, no-output-schema tool with annotations already covering the safety profile, the description supplies the missing pieces: what it writes, which files, and that existing prose survives. Only the behavior when target files or project.faf are absent is left unstated.

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 takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no configuration is required.

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 (Sync) plus the resource (project.faf) and enumerates the concrete target files (CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md), which is far more than a tautology. It does not, however, distinguish itself from close siblings like refresh_faf or faf_init, so an agent must infer the boundary.

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?

Usage is only implied: the agent can infer this runs after project.faf changes to propagate into AI context files, and 'every tool kept current' hints at the maintenance scenario. There is no explicit when-to-use statement, no prerequisites, and no mention of when to prefer refresh_faf or faf_init instead.

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 and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it shells out to faf-cli, checks well-formedness/parsing, and returns an "always-33 score," which is non-obvious behavior an agent could not derive from the schema.

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 tightly written sentences, front-loaded with the action and followed by the rationale. Every clause earns its place and there is no filler.

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-required-param, read-only validator with no output schema, the description covers what it does and what it returns (a score) well enough to call correctly. It could say more about failure output or how errors surface, but nothing essential is missing.

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 single optional path parameter is fully documented in the schema itself (directory to check, defaults to cwd). The description adds no parameter detail, so the 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?

Names a specific verb and resource: validates a project.faf via faf-cli and reports its score. The intent (confirm the context file parses cleanly) is concrete. It does not explicitly differentiate from the sibling faf_score, which also concerns scoring, so an agent must infer the split.

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 pre-flight trust check: never build on a broken context layer" implies the usage window (before an agent grounds on the file), which is real guidance. However, it never names an alternative or states when NOT to use it, and with faf_score and faf_init present as siblings, the routing choice is left implicit.

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 it is a non-readonly, idempotent, non-destructive, closed-world operation. The description adds genuinely new context: the effect is a full drop of cached retrievals and a source rebuild on the next query, which implies latency/cost the agent should anticipate. It doesn't address scope (per-session vs global) or authorization.

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 waste, with the action front-loaded and the usage condition following. Nothing is repeated from the schema or annotations.

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

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

For a zero-argument, no-output-schema mutation, the description covers what happens, what it affects downstream, and when to invoke it. Missing only edge details such as behavior on an empty cache and the blast radius across sessions, which the idempotent annotation partially mitigates.

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?

Zero parameters, so there is nothing to document and the baseline of 4 applies. The description's reference to "all cached retrievals" usefully confirms the operation is unfiltered and takes no arguments.

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 and resource ("Clear the LAZY-RAG cache") and immediately explains the mechanism: cached retrievals are dropped and the next rag_query rebuilds from source. This distinguishes it clearly from rag_cache_stats (read stats) and rag_query (consumes the cache).

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 an explicit trigger: "Use when the underlying context has changed and you want fresh results instead of cached ones." It names rag_query as the tool whose behavior changes, but stops short of stating when NOT to clear (e.g. cache is already fresh) or naming the stats sibling as a diagnostic alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful detail that this returns aggregate counters rather than raw entries, but says nothing about rate limits, cost, or whether the counters are cumulative or since-reset.

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

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

A single front-loaded sentence with the verb and resource first and the returned metrics listed after. Zero filler and no restatement of the title or schema.

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

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

With no output schema, the description carries the burden of describing return values and does so by naming the four metrics. It stops short of describing the response shape or units, which is a minor gap for a simple stats call.

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 takes zero parameters, which sets the baseline at 4. There is nothing for the description to disambiguate, and the schema coverage is 100% by definition.

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 (Get) plus resource (LAZY-RAG cache statistics) and enumerates the exact metrics returned: hits, misses, hit rate, cache size. It is clearly distinct from the sibling rag_cache_clear, but never names or contrasts that sibling explicitly, so it falls short of a 5.

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?

There is no explicit when-to-use or when-not-to-use statement, but usage is strongly implied: a zero-argument read of cache performance metrics is self-evidently for diagnosing cache effectiveness. No alternatives are referenced, so this is implied guidance rather than stated 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 declare readOnlyHint=true and openWorldHint=true, so safety and external-reach context is covered. The description adds genuine behavioral value by disclosing the LAZY-RAG cache layer and its speedup on repeated queries, but says nothing about latency on cache misses, auth requirements, or rate limits.

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

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

Two short, front-loaded sentences with no filler. The '100,000x speedup' figure leans promotional rather than operational, which costs a point, but the structure is otherwise clean.

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 tool with no output schema, nothing critical is missing to invoke it, but the definition never says what comes back (an answer only, or answer plus source context/citations). That omission is minor given the annotations, but it leaves the agent guessing at the response shape.

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

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

Schema coverage is 100% and the single 'question' parameter is self-explanatory, so the schema does the heavy lifting. The description adds no syntax, format, or scope detail beyond what the schema already provides, making the baseline 3 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 states a specific verb and resource: ask a question and get RAG-enhanced context from xAI Collections. It clearly identifies the tool's function and separates it from the cache-management siblings by name ('cache'), though it never names rag_cache_stats or rag_cache_clear 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?

There is no explicit guidance on when to use this versus alternatives. The mention of 'repeated queries' hints at the caching benefit but never tells the agent when to query directly, when to check rag_cache_stats, or when rag_cache_clear is relevant, leaving routing to inference.

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=false, destructiveHint=false, openWorldHint=false) only tell the agent it's a non-destructive write; the description adds real behavioral context by explaining the delta vs verbatim difference between modes and that intensity tracks drift per layer. It omits reversibility/auth/rate details, but goes meaningfully 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?

Front-loaded with the core action and combined-tool behavior, then mode distinctions. Dense with domain jargon (faf/fafm/soul) but every sentence carries information; slight density cost keeps it from a 5.

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 5-param, 0-required, no-output-schema tool, the description covers the mode semantics and how intensity maps to layers, which is enough to call it correctly. It does not address what a successful refresh returns or whether 'nuke' overwrites are reversible.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the mode enum and per-sub-tool applicability. The description's mode analogies add flavor but no syntax or format detail beyond what the schema provides, so the baseline 3 holds.

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 (refresh) and resource (blend = .faf + .fafm) and explicitly says it 'Fires BOTH `refresh_faf` + `refresh_fafm` in one call,' which directly distinguishes it from those two 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?

Clearly frames each mode's use case: 'blend' is 'the everyday re-ground' and 'nuke' is 'the hard reload for polluted session memory,' giving concrete selection criteria. It stops short of saying when to prefer the underlying refresh_faf/refresh_fafm over this combined call.

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 declare readOnlyHint=false and destructiveHint=false, which opens the question of whether re-grounding persists state; the description only says it re-reads, re-scores and returns context, and never discloses writes, caching, or side effects. It adds the drift-report behavior, which is useful, but leaves the non-read-only hint unexplained.

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 opening clause is front-loaded and precise, but 'drift → refresh → re-grounded' and 'Built for Grok, by request' are filler that consume space without helping an agent decide or invoke correctly.

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 only two optional parameters and no output schema, the description adequately covers the trigger condition and that a drift delta plus fresh context are returned, but 'return the fresh context' is left vague for a tool whose entire value is that returned context.

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

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

Schema coverage is 100%, so both parameters are already documented and the baseline 3 applies. The description reinforces the purpose of 'baseline' ('report drift vs your last-known score') but adds no syntax or format detail 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?

Specific verb+resource: 're-read + re-score the current project DNA' and 're-ground on the live .faf'. This is clearly distinct from refresh_blend/refresh_fafm in intent, though it never names the sibling it most overlaps with (faf_score) to explain the difference in practice.

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 implies usage via 'The explicit re-grounding primitive for long sessions: drift → refresh → re-grounded', which tells the agent it is a session-maintenance call, but gives no explicit when-not or alternatives (e.g., why not just call faf_score again).

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 readOnlyHint=false, the description correctly discloses the side effect that matters: it reads files and writes a refresh receipt (.fafm-refresh-receipts.json) to the project folder. It also guarantees a content hash + timestamp stamp and states that 'since' is ignored under verbatim, which is real behavioral context beyond the annotations. Gaps remain around failure behavior and what a refresh does to in-session state.

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?

Front-loaded with the core action and default return, then layers side effects and routing. Five sentences is slightly dense for three parameters, but every sentence carries usable information and none is filler.

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

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

With no output schema, the description carries the return-value burden and does so: stamped delta with added/updated facts, hash + timestamp, or full content under verbatim. The only missing piece is what the receipt file contains and whether refresh is idempotent.

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

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

Schema description coverage is 100%, so the schema already documents soul, since, and verbatim in full. The description restates the since/verbatim interaction rather than adding new semantics, so the 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+resource: reload the latest structured memory (.fafm) for souls into the current session, and clarifies the default return shape (stamped delta). It also positions itself relative to recall/load_soul/etch, though those are not siblings in the supplied list, so the differentiation against the actual sibling set (refresh_faf, refresh_blend) is weaker than it could be.

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 clear operational guidance: deltas are the default, use verbatim:true for full content and 'sparingly', and it explicitly says it complements rather than replaces related tools. It stops short of an explicit when-not-to-use condition or any prerequisite/permission statement.

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