Praxis Lite

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

With no annotations, the description carries the behavioral burden. It discloses idempotency and the user-approval prompt for external agents, which are valuable operational details. It does not mention error handling or permissions, but for a simple create operation this is above average.

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

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

Two sentences with no filler. The core action is front-loaded, and the idempotency and approval notes are relevant and concise. 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?

For a single-parameter tool with an output schema (not shown), the description covers the key behavioral aspects: idempotency and user approval. It is sufficient for an agent to understand what will happen when called, though it does not explain return values (likely covered by the output schema). Overall, it is appropriately complete for its simplicity.

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 has 0% description coverage, and the description does not explain the 'path' parameter beyond its name. The 'parents included' note hints at nested paths, but there is no guidance on path format, relative vs absolute, or other constraints. The description fails to compensate for the missing schema documentation.

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 'Create' and the resource 'directory', with the additional note 'parents included' which specifies scope. It is unambiguous and easily distinguished from fs_create_file and other file 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?

The description implies use for directory creation but does not explicitly state when to use this tool over alternatives, nor does it mention exclusions (e.g., use fs_create_file for files). The purpose is obvious, but no explicit routing 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 provided, the description carries the full disclosive burden. It goes beyond the name by revealing that creation is refused for existing paths and that external agents will trigger a user-approval prompt. This is strong behavioral context, though it does not mention edge cases like missing parent directories or partial write behavior.

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

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

The description is compact and well front-loaded: the core action is in the first sentence, the key caveat is second, and the approval prompt is last. Every sentence earns its place without 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 two-parameter tool with an output schema and low complexity, the description covers the essential behavior: create new file, refuse existing, use fs_overwrite alternatively, and expect user approval. Minor unspecified details like parent directory handling are not critical for correct 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 0%, so the description must compensate. It adds meaning by specifying that content is UTF-8 and that the path must be a non-existing target path. However, it does not clarify path format, semantics, or constraints beyond existence, so compensation is only partial.

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

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

The description opens with a specific verb and resource: 'Create a new file with the given UTF-8 content.' It also distinguishes itself from the sibling fs_overwrite by explicitly stating this tool refuses existing paths, so an agent can immediately tell which tool to pick.

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 guidance is explicit: 'Refuses if the path already exists — use fs_overwrite (T2) to replace an existing file.' This states both the limiting condition and the correct alternative, leaving no ambiguity about when to choose this tool versus its sibling.

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 discloses key behaviors: files are moved to trash, not hard-deleted, with a 24h retention, and restoration is possible. It also details external agent blocking and local user 2FA. This is substantial coverage, though it doesn't specify error handling or what happens after retention expires.

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 and well-structured, with the core behavior front-loaded. It uses minimal words to convey critical safety and security information. Each sentence serves a purpose, from trash staging to access restrictions.

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 complexity (with security layers), the description covers most essentials: what happens (trash), retention, restoration, access controls, and user verification. An output schema exists, so return values are not needed. Minor gaps include handling of non-existent paths or batch operations, but these are not critical.

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

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

Schema coverage is 0%, but there's only one parameter 'paths', and the description mentions 'delete file(s)' implying paths. However, the description doesn't clarify whether paths can be directories or glob patterns, nor does it explain the expected format. The schema's 'array of strings' is minimal, and the description adds limited value beyond that.

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 deletes file(s), with the specific verb 'Delete' and resource 'file(s)'. It distinguishes from siblings by emphasizing the trash staging. However, it doesn't explicitly differentiate from write/overwrite or other mutation tools, but the context makes the purpose clear.

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 (for deletion) but doesn't detail when not to use it or alternatives. It mentions restrictions for external agents and local user authentication, which guides usage, but lacks explicit comparison to other tools like fs_move or fs_overwrite for similar operations.

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 must carry the behavioral burden, and it does state the key behavior: listing only direct children and treating an empty glob as 'list everything.' It does not disclose details such as hidden-file inclusion, ordering, or error handling, but these are relatively minor for a read-only 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?

One front-loaded summary sentence plus two terse, informative argument bullets. No filler, no repeated schema title, and 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 two-parameter listing tool with an output schema present, the description provides enough invocation information: path, optional filter, and non-recursive scope. It omits minor details like whether directories themselves are included or how hidden files are treated, but these do not block correct 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 0%, so the description is the only source of parameter meaning. It explains both parameters clearly: path is 'the directory to list' and glob is an optional shell-style pattern with an explicit empty-default behavior and a concrete example ('*.pdf').

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

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

The description opens with a specific imperative: 'List entries directly under a directory,' identifying both the operation and the resource. The phrase 'directly under' clarifies that this is a non-recursive, immediate-child listing, which helps separate it from search and read tools, though it never explicitly names or contrasts a sibling.

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 implied by the summary and arguments: call it when you need the immediate children of a path, optionally filtered by a glob. There is no explicit guidance about when to choose fs_search, fs_read, or fs_stat instead, and no 'do not use when' 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?

The description includes the warning 'Destructive → T2', which flags that the operation can destroy data—an important disclosure given that no annotations are provided. However, 'T2' is undefined and the description does not explain what is destroyed (source files? overwritten targets?) or whether the operation is reversible. The warning adds value but is incomplete.

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 definition is two short sentences with no filler; the core action and the destructiveness warning are front-loaded. This is an appropriate size for such a simple tool, though the cryptic 'T2' could be clearer.

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 destructive operation with no annotations and 0% schema coverage, the description is too thin—it lacks usage guidance, parameter behavior, and a definition of 'T2'. While the output schema may cover return values, an agent still cannot determine safe invocation conditions, overwrite policy, or how this differs from fs_rename.

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 documents paths and target_dir, and the description only restates them in prose ('file(s)', 'target directory') without adding semantics such as handling of existing files, glob patterns, or path normalization. With schema description coverage at 0%, the description fails to compensate for the missing parameter details.

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 first sentence names the action (move), the resource (file(s)), and the destination (target directory), which clearly separates it from sibling tools like fs_delete or fs_read. It does not explicitly differentiate from fs_rename, so it stops 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?

The description provides no guidance on when to choose fs_move over fs_rename, fs_overwrite, or fs_delete, nor does it state prerequisites (e.g., source must exist, target directory must exist). This leaves the agent to infer usage from the tool name alone.

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

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

No annotations are present, so the description carries the burden of disclosing side effects. It does this well by stating that the original is backed up to trash first and that a recoverable copy remains in ~/.praxis/trash/. This goes beyond what the name or schema alone reveal.

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

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

Two short sentences with no wasted words. The core action and side-effect are front-loaded, and the comparison to fs_write is placed exactly where it helps decision-making.

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 only two straightforward parameters and an output schema, the description covers purpose, mutation behavior, recoverability, and the sibling relationship. It doesn't discuss error cases like missing files, but the phrase 'existing file' and the output schema make the definition adequate for correct 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 0%, so the description must compensate. It implies path refers to the existing file and content is the replacement text, and the wording 'existing file' adds a useful constraint. However, it never directly explains either parameter, so it only partially compensates for the schema's lack of 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 names a specific verb and resource: overwrite an existing file. It also explicitly differentiates itself from fs_write, so an agent can distinguish this tool from its closest sibling without needing to inspect 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?

The description frames when to prefer this tool by contrasting it with fs_write: this one replaces existing content but always keeps a recoverable trash copy. It doesn't explicitly say 'use this when you need a backup,' but the comparison gives clear contextual 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 provided, the description carries full behavioral burden and handles it well. It discloses a surprising security restriction (refuses credential stores 'regardless of principal'), which an agent could not infer from the schema, and explains truncation behavior including the result.truncated flag. This is genuinely valuable beyond the structured data.

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, each earning its place: purpose first, then security refusal, then truncation behavior. No fluff, no repetition, and the most important operational constraints are packed efficiently.

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 two-parameter tool, the presence of an output schema, and the absence of annotations, the description covers the essential context: what it reads, what it refuses to read, and how large files are handled. Nothing critical is missing for successful invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning to max_bytes by explaining the truncation limit and default cap. Path is self-evident and needs no elaboration. The only small gap is not explicitly stating what max_bytes=0 means, though 'or the executor's default cap' partially covers it.

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 starts with a specific verb and resource: 'Read a file's bytes as a UTF-8 string.' This unambiguously distinguishes fs_read from siblings like fs_stat (metadata), fs_search (search), and fs_list_dir (directory listing) without needing further inference.

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 clear (read file content), but there is no explicit 'when to use this vs. alternative' guidance, nor any mention of siblings like fs_stat or fs_search. The context implies usage rather than stating it, so an agent must infer routing from the name and one-liner.

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 discloses the rename-in-place behavior and the basename constraint, but does not mention overwrite behavior, error conditions, permissions, or side effects—important gaps for a mutation 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 sentence with no filler. The core behavior is front-loaded, and the only added constraint earns its place. It is concise without being under-specified.

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 low-complexity two-parameter tool, the description gives the essential rename-in-place semantics and a critical parameter constraint. With no annotations, though, an agent still lacks guidance on overwrite behavior and failure modes, making this minimally viable rather than 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 description coverage is 0%, so the description must compensate. It adds useful meaning for new_name by requiring a basename, and 'in place' clarifies that path is the source directory. However, path semantics are not directly described beyond this inference.

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 ('Rename'), a resource ('file'), and a precise scope ('in place'). It also adds the key constraint that new_name must be a basename, which distinguishes it from a move operation and from the sibling tool fs_move.

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

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

The phrase 'in place' and the basename constraint imply this tool is for renaming within the same directory rather than moving files. However, it never explicitly states when to prefer this over fs_move or when not to use it.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses fuzzy matching, case-insensitivity, synonym expansion, ranking factors (fuzzy match, recency, directory prior), directory prior examples, and the structure of returned hits. This is substantially more transparent than typical tool descriptions.

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 well-structured with an intro, ranking explanation, Args section, and Returns section. Every sentence adds information; the ranking example ('Documents outrank Library/Caches') is illustrative without being verbose.

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

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

For a search tool with four parameters, the description covers input semantics, default behavior, ranking behavior, and the exact return shape. Even with an output schema present, the description gives an agent everything needed to invoke the tool correctly and interpret results.

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 0%, so the description must fully compensate, and it does. Each parameter (query, paths, ext, limit) gets meaningful semantics: query's case-insensitivity and synonyms, paths' fallback to the home directory when empty, ext as an example filter, and limit's default value.

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

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

The description opens with a specific verb-resource pair: 'Search the user's disk by filename', and clarifies it is a fuzzy search. It also distinguishes itself from directory/file manipulation siblings by focusing on ranked filename search.

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

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

The description clearly conveys the intended use case: find files by filename, optionally scoped by paths and extension. It does not explicitly name alternatives or exclusion conditions, but the context is strong enough that an agent would not confuse this with fs_list_dir or fs_read.

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 of behavioral disclosure. It does convey that this is a read-only metadata operation and lists the result fields, but it does not disclose failure behavior for missing paths, symlink handling, or whether it works on both files and directories (though is_dir/is_file hint at this). The core read-only nature is implied but not explicit.

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 zero filler. It states the action and the key output fields efficiently, earning its place without any unnecessary detail.

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

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

The tool is simple, has an output schema, and the description lists the returned fields, so return-value details are covered. However, the description lacks usage guidance and path expectations, which would be valuable given the sibling tools. It is minimally adequate but leaves the agent to infer when and how to invoke 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?

Schema description coverage is 0%, so the description must compensate. However, it merely says 'for a path', which only restates the schema's 'path' title without adding meaning about path format (absolute vs relative), whether the path must exist, or what constitutes a valid input. It fails to add any semantic value beyond the parameter name.

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 ('Return metadata') and resource ('for a path'), and enumerates the returned fields (size, mtime, mode, is_dir, is_file). This clearly distinguishes fs_stat from siblings like fs_read (content) and fs_list_dir (directory entries), so an agent knows exactly what operation this is.

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 that this tool is for inspecting file metadata rather than content, but it never explicitly says when to use it versus fs_read or fs_list_dir. There is no when-to-use guidance, no exclusions, and no mention of alternatives; the agent must infer the intended use from the tool name and the words 'metadata'.

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 behavioral burden. It discloses important traits: UTF-8 encoding, default refusal on existing files, append behavior, and the write-vs-overwrite distinction. It omits minor details such as success/error shapes, but the output schema covers return values.

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

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

The description is short and front-loaded with a one-line purpose before the parameter details. It is slightly less polished than ideal because of the inline formatting and the unexplained 'T2 op' phrase, but it has 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 three-parameter file-writing tool, this covers the essential call contract: destination, content, and existence behavior, plus the overwrite alternative. The lack of an example or explicit error conditions is a minor gap, and the output schema covers return values.

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 0%, and the description compensates fully: path is identified as the destination file, content as the text to write, and if_exists is explained with its default ('error' means refuse) and alternative ('append' means add to end). This is effectively the only source of parameter meaning.

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

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

The opening line states a concrete verb and resource: 'Write UTF-8 bytes to a file.' It also distinguishes itself from the closest sibling by explicitly saying that overwriting an existing file is a T2 op and should be handled by fs_overwrite, so an agent can tell it apart without opening the 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 gives explicit routing guidance: overwriting an existing file should go to fs_overwrite, not this tool. It also clarifies the two intended usage modes through if_exists: refuse by default or append. This is enough for an agent to decide when to select fs_write versus the overwrite 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?

With no annotations, the description carries the burden of behavioral disclosure. 'Report' implies a read-only query with no side effects, and the enumerated outputs give useful contextage. However, it does not explicitly state whether authentication, daemon availability, or cost considerations apply, leaving some behavior implicit.

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 names the tool's purpose and outputs with zero filler. Every word contributes meaning.

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 status tool with an output schema, the description is complete: it states the three status dimensions, and return-value details are presumably captured by the output schema. No additional context is necessary for correct invocation.

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

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

The tool has zero parameters, so the baseline is 4. The description adds no parameter details, but none are needed since the input schema is empty and schema coverage is 100%.

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 ('Report') with a clear resource ('the daemon') and enumerates the concrete status dimensions: current principal, trash size, and health. This clearly distinguishes it from the file-oriented fs_* 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?

There is no explicit when-to-use or alternative guidance, but as a zero-parameter status tool the intended usage is strongly implied by the name and description. It does not state exclusions or scenarios, though none are critical given the tool's simplicity.

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