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

With no annotations provided, the description carries the full burden and discloses key behaviors: writes go to an in-memory overlay and do not touch the real filesystem unless committed, and network is disabled unless JUST_BASH_NETWORK_ALLOW is set. This goes beyond a simple 'executes bash' and informs the agent about side effects and limitations.

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

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

Three sentences efficiently convey the core purpose, sandboxing behavior, network conditions, and supported tools. The list of supported commands is long but necessary for capability discovery, and the description is front-loaded with the primary action.

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 bash execution tool with no output schema, the description covers critical behavioral constraints: sandboxed filesystem, network restriction, available commands, and optional runtimes. It omits return value format and commit mechanism, but given the complexity, the description is reasonably complete without being 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?

Schema description coverage is 100% for both parameters (script and timeout), so the baseline is 3. The description does not add specific parameter semantics beyond the schema, but it does contextualize the execution environment, which indirectly supports understanding of the script 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 'Execute a bash script in a sandboxed virtual filesystem mounted at the project root' – a specific verb, resource, and environment. It distinguishes from siblings like sandbox_status and sandbox_reset, which deal with sandbox state rather than execution.

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

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

Provides clear context about the sandbox environment, network restrictions, and supported commands, implying when to use it for isolated bash tasks. Does not explicitly name alternatives or state exclusions, but the environmental guidance is sufficient for a single-purpose tool.

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

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

With no annotations provided, the description is the sole source of behavioral disclosure. It honestly states that the tool modifies project.faf in place on the real filesystem, alerting the agent that this is a potentially destructive operation with real side effects. It could have added more detail (e.g., reversibility, failure modes), but the core risk is communicated clearly.

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 succinct and well-structured, with three short sentences that each serve a distinct purpose: stating the action, warning about the real filesystem, and noting the in-place modification. There is no extraneous 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 simple tool with one optional parameter and no output schema, the description covers all essential aspects: what the command does, where it operates, and its side effects. It is complete enough for an agent to correctly select and invoke the tool without ambiguity.

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 documents the only parameter ('project') with a full description and default behavior. The description adds no extra semantic detail beyond what's in the schema, so the baseline score of 3 is appropriate given the 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 clearly states a specific action: run `faf migrate` on a project directory to upgrade project.faf to the latest schema version. It names the target resource (project.faf) and the effect (schema upgrade), and differs from siblings like bash_exec, faf_sync, and faf_score with its focus on migrating schema.

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

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

The description provides clear context for when to use the tool (when a schema migration is needed) and includes an important caveat that it operates on the real filesystem, bypassing the bash sandbox. However, it does not explicitly mention alternatives or state exclusions, so it stops just short of perfect 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, the description carries the full burden. It discloses key behavioral traits: 'Operates on the REAL filesystem' and 'Overwrites SOUL.md in the project root', which alert the agent to destructive, non-sandboxed behavior. This is valuable context, though it does not mention error handling or idempotency.

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 providing new information: the command and its purpose, the real-filesystem caveat, and the overwrite behavior. No filler or 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?

Given the simple tool with one parameter and no output schema, the description covers the purpose, operation, and key safety warning. It does not discuss return values or error cases, but these are less critical for a file-generation command.

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

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

The schema already documents the single 'project' parameter with 100% coverage. The description adds no additional parameter-level detail beyond what the schema 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 'Run `faf-moltbot sync` on a project directory to generate SOUL.md' — a specific verb, command, and output resource. It also distinguishes itself by noting it overwrites SOUL.md in the project root, making the tool's function unambiguous.

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

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

The description provides context that this tool is for generating SOUL.md in a project directory and operates on the real filesystem, but it does not explicitly compare with sibling tools like faf_sync or state when to prefer this tool over alternatives. The real-filesystem warning implies caution, but no explicit when/when-not guidance is 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?

With no annotations provided, the description carries the burden. It does disclose important traits: read-only and operates on the real filesystem. However, it omits details like command availability, error behavior, or what the report representation means beyond color/percentage, so it is only moderately transparent.

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 extraordinarily concise: three short sentences, front-loaded with the action and purpose, with no redundant words.

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

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

Despite lacking a output schema and annotations, the description covers the essential aspects: what it does, key safety trait (read-only), and the real-filesystem caveat. Minor gaps like error handling are not critical for such a simple tool, but it could be slightly richer.

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 `project` is fully described in the schema, including its default. Schema coverage is 100%, so the description does not need to add parameter details; it does not go beyond the schema, hence baseline 3.

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

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

The description clearly states the verb and resource: "Run `faf score` on a project directory" to produce a "quality report" with specific outputs (slot fill %, color). This distinguishes the tool from sibling migration/sync 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 clear usage context: when you need a quality report for a project directory. It also notes the tool is read-only, signaling safe use, but does not explicitly mention alternatives or when-not to use it compared to 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?

With no annotations present, the description carries the full burden and delivers: it warns that 'Operates on the REAL filesystem' (non-sandboxed side effects) and 'May overwrite faf-generated AGENTS.md', plus provides a mitigation ('use a custom AGENTS.md'). This is strong behavioral disclosure.

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: the first states the action and purpose, the second warns about the real filesystem, and the third explains the overwrite risk and how to avoid it. Every word earns its place, and the most important 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?

For a single-optional-parameter tool with no output schema, the description covers the command, its purpose, the project input, and critical side-effect warnings. It doesn't describe return values or error conditions, but those are less critical given the simplicity and the provided warnings.

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 covers 100% of the sole parameter with a clear description including the default. The tool description adds no extra parameter-level insight beyond the phrase 'project directory', so the 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 explicitly states the command (`faf sync`), the resource (project directory), and the desired outcome (regenerate CLAUDE.md and other agent docs from project.faf). This specificity distinguishes it from sibling faf tools like faf_migrate 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?

The description gives a clear context: it regenerates docs and operates on the real filesystem, implying caution. However, it does not explicitly mention alternative tools or conditions under which this tool should not be used, so it falls short of full usage 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, the description carries the full transparency burden. It adds a valuable detail about checking both overlay and real filesystem, but it does not disclose return behavior (e.g., boolean vs exception), side effects, or permissions. For a simple existence check, this is adequate but not exhaustive.

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

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

The description is a single, front-loaded sentence with no redundant wording. It communicates the core purpose and an important scoping detail efficiently, earning a top score.

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

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

The tool is simple, with one fully described parameter and no output schema. The description covers the operation's scope (sandbox, overlay+real fs) adequately. However, because no output schema exists, explicitly stating the return type (e.g., true/false) 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 schema already provides full coverage for the single parameter (sandboxPath). The description adds no additional parameter-level meaning beyond what the schema states, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool checks if a path exists in the sandbox, with a specific verb and resource. It mentions the overlay+real fs scope, providing useful context. However, it does not explicitly distinguish itself from sibling tools like realpath or bash_exec, so it's not 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?

The intended use is implied (when you need to verify path existence in the sandbox), but no explicit guidance is given about when to prefer this over alternatives. There are no exclusions or alternative tool references, so it falls short of clear usage direction.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the core resolution behavior but omits details about error handling, what happens for invalid paths, whether it resolves symlinks, or any permissions needed. This is a significant gap for a tool with no annotation support.

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 that states the tool's purpose and context. Every word earns its place, with no redundancy or 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?

The tool is simple (one parameter, no output schema, no annotations), and the description adequately conveys its primary function. However, it omits details about return behavior and edge cases, which would be useful for a complete understanding. Given the low complexity, this is a minor gap.

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

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

The input schema already provides 100% coverage for the single sandboxPath parameter with an example. The description adds context about the purpose (real path resolution) but does not add syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb 'resolve' and the resource 'sandbox path to its real filesystem path', distinguishing it from siblings like path_exists (which checks existence) and bash_exec (which executes). The parenthetical 'for reading or committing' adds useful context about the tool's intended use.

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 it (when you need the real filesystem path for reading or committing) but does not explicitly compare it to alternatives like path_exists or sandbox_status. No when-not-to-use guidance is provided.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It explicitly states the destructive nature: 'drops all in-memory writes,' and clarifies that a fresh sandbox is created from the real project state. This explains the key side effect without requiring a permissions or rate limit note.

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: the first states the action and its effect, the second gives the use case. It is front-loaded, concise, 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?

This is a simple tool with one parameter and no output schema. The description covers purpose, usage, and the key behavioral detail (in-memory writes dropped). It doesn't explain return values, but given the low complexity, this is not a critical gap. A slightly more explicit note about the result of the reset could push it to 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% as the only parameter `confirm` has a clear description: 'Must be true to confirm destruction of in-memory writes.' The tool description does not add extra parameter semantics beyond reinforcing this destructive behavior, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's action: 'Discard the current sandbox (drops all in-memory writes) and create a fresh one.' It specifies the resource (sandbox) and the verb (discard/reset), and distinguishes it from siblings like sandbox_status by focusing on resetting rather than checking status.

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 explicit guidance on when to use it: 'Use this when you want to start over from the real project state.' This clearly indicates the use case, but it does not mention when not to use it or explicitly name alternatives, so it falls short of a full 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?

No annotations are provided, so the description carries the burden. It explicitly says 'Show', indicating a read-only operation, and enumerates the output fields. However, it does not disclose error behaviors, permissions, or whether the sandbox might be uninitialized, though the simplicity of a status check mitigates this.

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 that states the purpose and lists the key attributes. Every element is informative 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?

With no output schema, the description provides the main return fields, which is good for a simple status tool. It lacks details on data types or formats (e.g., age in seconds), but given the low complexity and zero parameters, this is largely sufficient.

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

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

The input schema is an empty object with zero parameters. The description compensates by clearly enumerating the output fields (project root, age, exec count, last script, network policy), which effectively tells the user what to expect from the call, exceeding the baseline of 4 for zero-parameter tools.

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 ('Show') and clearly identifies the resource ('current sandbox state') and explicitly lists the fields included. This distinguishes it from siblings like sandbox_reset and bash_exec, which focus on actions rather than status inspection.

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 use for checking status, and the sibling names are clearly distinct, but there is no explicit 'when to use' or exclusions. It lacks explicit guidance on when not to use or which alternative to choose for other purposes.

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