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 does disclose that the tool returns a security audit report with a health score, exposed .env files, and recommendations, implying a read-only analysis. However, it never explicitly states that the workspace is not modified, nor does it mention access requirements or scanning 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?

The description is compact and front-loaded. The opening sentence states the tool's purpose, followed by minimal Args and Returns sections. There is no filler, repetition, or unnecessary detail.

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

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

For a tool with one optional parameter and an output schema, the description is mostly complete: it covers the parameter and summarizes the report contents. It loses a point because it does not position itself among five sibling tools, leaving the agent to infer when to choose it over scan_workspace or get_workspace_health.

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

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

The input schema has no property descriptions and schema coverage is 0%, so the description must fully document the single parameter. It does so clearly: 'path: Root directory to audit.' This adds directory-specific meaning beyond the schema's 'Path' title and 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 uses a specific verb and resource: 'Audit workspace for security risks', and details the exact scope: untracked .env files, exposed API keys, and workspace hygiene. This clearly distinguishes it from siblings like scan_workspace and get_workspace_health, which have more general or health-focused purposes.

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

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

No explicit guidance is given about when to use this tool versus alternatives such as scan_workspace, preview_cleanup, or get_workspace_health. The description says what the tool does but not under which conditions it should be selected, and it provides no exclusions or mention of sibling tools.

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 clearly explains dry_run safety behavior, the difference between trash and permanent deletion, and that a clean report is returned. While it could elaborate on what 'safety checks' entail or the irreversibility of permanent mode, the core destructive behavior is disclosed.

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

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

The description is well-structured and front-loaded: a one-sentence summary, a prominent safety warning, a compact Args list, and a Returns note. Every sentence contributes directly to correct usage, and there is 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 description covers all parameters, the default safety behavior, both deletion modes, and the return value, which is sufficient for invoking the tool. It is slightly incomplete in that it does not discuss tool-selection tradeoffs with siblings or define the 'non-secret artifacts matching criteria' any further, but these are secondary to 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 fully compensate, and it does. Every parameter—path, target_paths, artifact_types, mode, and dry_run—receives a meaningful explanation beyond the raw schema types and defaults. This gives an agent enough context to invoke the tool correctly.

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

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

The description opens with a clear verb and resource, 'Clean reclaimable developer artifacts', making the tool's purpose immediately understandable. It does not explicitly distinguish itself from siblings like preview_cleanup or scan_workspace, but the resource and action are specific enough to avoid confusion.

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 clear operational guidance, especially the important dry_run default and the fact that explicit paths can be provided. However, it does not say when to use this tool versus preview_cleanup, scan_workspace, or other sibling tools, and no exclusions are stated. Usage context is mostly implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It does disclose that the call retrieves history and returns 'scan records and cleanup logs with totals and metrics,' which implies a read-only operation. However, it does not explicitly confirm non-mutating behavior, permissions, or pagination semantics.

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

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

The description is compact and front-loaded: one clear purpose sentence followed by a terse Args section and a short Returns line. Every line adds information; there is no repetition of the schema or irrelevant details.

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 read-only history tool with an output schema, the description covers the purpose, both parameters, and the return shape. It does not mention authentication requirements or rate limits, but these are less critical for a low-risk retrieval operation, and the existing detail 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?

Schema description coverage is 0%, but the description compensates by explaining both parameters: path is an optional workspace root directory filter, and limit is a maximum record count with a default of 10. This adds real meaning beyond the raw schema, only leaving ambiguous the exact path format and behavior when path is omitted.

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-object pair: 'Retrieve historical workspace audit scans and cleanup activity logs.' This clearly identifies the resource (audit history) and the action (retrieve), while 'historical' distinguishes it from sibling actions like scan_workspace or audit_workspace_secrets.

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 'historical workspace audit scans and cleanup activity logs' implies this is for past activity rather than current scans, but the description does not explicitly state when to use this tool instead of a sibling, nor does it name any alternatives or exclusions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly frames the operation as a read-style 'Get' and describes the summary output, which is helpful. However, it does not explicitly state that the tool is non-mutating, whether deeper scanning occurs, or any permission/performance considerations, leaving some behavioral ambiguity.

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

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

The description is compact and well-structured: a one-sentence purpose, an Args line, and a Returns line. There is no filler or repetition, 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 simple read-only health check with a single optional parameter and an output schema, the description covers the essential calling information and summaries what will be returned. The main gap is the lack of explicit guidance on when to choose this tool over sibling scanning/cleanup tools, but that is a minor omission given the tool's straightforward nature.

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 gives the parameter only a title ('Path'), a default, and a type, with no description. The tool description compensates by explaining that path is the 'Workspace root directory,' adding real meaning. It does not mention default behavior when omitted, but the schema already exposes that default, so the added semantics are sufficient.

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

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

The description states a clear verb and resource: 'Get high-level health overview and disk space metrics for a developer workspace.' It also lists the returned metric categories, which helps define scope. However, it does not explicitly contrast itself with sibling tools like scan_workspace or audit_workspace_secrets, so it stops short of full differentiation.

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

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

The phrase 'high-level health overview' implies this tool is for an initial or summary check, and the return categories suggest it surfaces broad issues before deeper action. But the description does not name alternatives or state when to prefer scan_workspace, preview_cleanup, or audit_workspace_secrets. Usage guidance is only implied, not explicit.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this well by explicitly stating this is a dry-run simulation and that it returns 'items that would be removed' and reclaimable bytes, establishing a non-destructive preview. It stops short of an absolute statement like 'no files will be modified', but the dry-run terminology strongly implies it.

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 tightly structured with a one-sentence purpose, a clear Args section, and a Returns section. Every line earns its place, and the most important trait—dry-run/preview—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 tool with four optional parameters and an output schema, the description covers the input semantics and the return shape sufficiently. It could be slightly more complete by explicitly directing the agent to clean_workspace for actual execution or restating that no changes are made, but the existing content is 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 for missing parameter documentation. It does: every parameter is listed with a meaningful one-line explanation, and 'older_than_days' gains important context as 'inactive for at least N days'. This adds real semantics beyond the raw schema fields.

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 'Dry-run simulation of workspace cleanup', which names a specific verb (simulate/preview) and a clear resource (workspace cleanup). It also differentiates itself from the sibling clean_workspace by framing this as a preview 'before executing', so an agent can immediately tell it apart from the actual cleanup tool.

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

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

The description clearly implies the tool is for planning: inspect items and reclaimable space 'before executing'. It does not explicitly name clean_workspace as the alternative to run when actual cleanup is intended, but the dry-run framing and 'before executing' language provide 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 the full behavioral burden. It does disclose the return shape ('Structured scan report with discovered items, sizes, categories, and secret warnings'), and the word 'scan' implies read-only behavior. However, it never explicitly states that it does not modify or clean the workspace, nor does it disclose permission needs or runtime implications.

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, front-loaded with the core purpose, and uses clear Args/Returns sections. Every line adds useful information, and the artifact_types list is necessary because the schema lacks enums. Nothing is wasted.

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

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

The description covers the tool's purpose, all parameters, defaults, allowed filter values, and return report, so an agent can invoke it correctly. It is slightly incomplete only in not providing sibling routing or an explicit read-only guarantee, but for a pure-scan tool with an output schema this is nearly 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?

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It documents all four parameters with defaults and adds meaning absent from the schema, especially the allowed artifact_types list ('node_modules', 'python_venv', 'python_cache', 'build_artifact', 'temp_logs', 'env_secret'). This gives the agent everything needed to construct valid 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?

The description uses a specific verb and resource ('Scan a developer workspace') and enumerates concrete target categories: build files, virtualenvs, caches, and secret files. It does not explicitly differentiate itself from siblings like audit_workspace_secrets or clean_workspace, so it lacks explicit sibling distinction but is still 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 main sentence implies when to use it: when you need a scan report of reclaimable artifacts in a workspace. However, it never tells the agent when not to use this tool or how it compares to alternatives such as audit_workspace_secrets, preview_cleanup, or clean_workspace. This leaves routing decisions to inference.

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