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

No annotations provided, so description carries full burden. Discloses independent step execution, artifact generation, reuse of per-layer SVGs, and that failure in one step doesn't halt others. Describes return format as a multi-line summary with per-artifact status. Fully transparent with no contradictions.

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 relatively long but well-structured with numbered steps, bullet points, and clear separation of concerns. Each sentence serves a purpose, though some minor redundancy could be trimmed. Front-loaded with main purpose.

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

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

Given the tool's complexity (multi-step, multiple artifacts, error handling), the description is complete: covers all steps, artifacts, error behavior, output format, and links to alternatives. Output schema exists (though not detailed) but description adequately describes return summary. No gaps.

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 parameter, master, with 0% schema description coverage. The description adds meaning by specifying accepted formats: 'Master filename inside the working directory (e.g. [MASTER]office.nsm) or an absolute path inside the active workspace.' This clarifies type and constraints beyond the schema.

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

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

The description clearly states the tool generates a default deliverable bundle for a .nsm master, listing three specific steps with artifact types. It distinguishes from sibling tools like export_diagram, export_device_table_html, and get_ai_context by recommending this tool for routine finalization rather than individual calls.

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 'Call this ONCE as the final step after constructing or substantially updating a network.' Also specifies when not to use (per-area combined HTMLs) and directs to use run_commands for that case. Provides clear guidance on preference over individual export calls.

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

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

With no annotations, the description carries full burden. It transparently explains the internal process: creating a temporary .xlsx in a system temp directory and converting it to .nsm, leaving no artifact. It also details filename constraints. However, side effects like overwriting are not mentioned.

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 a clear main action, process explanation, parameter details, and return value. It is slightly verbose in explaining the internal conversion but every sentence is informative.

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 annotations, the description covers purpose, process, parameter constraints, and return type. It does not detail error conditions or output schema fields, but the provided information is sufficient for basic usage.

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

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

Schema coverage is 0%, so the description must compensate. It explains the single parameter 'filename' thoroughly: optional, must start with '[MASTER]', end with '.nsm', no path separators, and default value. This adds significant value beyond the sparse schema.

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

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

The description clearly states the verb 'Create' and the resource 'new empty Network Sketcher master file (.nsm)'. It distinguishes from sibling tools like export_master_xlsx and import_master by focusing on creating a blank master from scratch.

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 usage for creating a new empty master file but lacks explicit guidance on when to use this tool versus alternatives (e.g., import_master). No when-not scenarios are mentioned.

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. It details output characteristics (single self-contained HTML, four tabs, no external references, specific file naming) and the prerequisite. It does not mention if the tool overwrites existing files or handle errors, but it sufficiently discloses the main 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 well-structured and front-loaded: purpose, output details, prerequisite, parameter. Every sentence adds value without redundancy. It is concise yet comprehensive, fitting the tool's complexity.

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 single parameter, clear prerequisite, and output summary mention, the description is largely complete. It lacks potential error scenarios or size/boundary notes, but overall it provides sufficient context for an agent to invoke the tool 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?

Schema description coverage is 0%, so the description must compensate. It explains the 'master' parameter (filename inside working directory or absolute path, .nsm master). This adds meaning beyond the schema, though it could specify the expected file extension more explicitly.

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 clear action verb and resource: 'Export an interactive HTML Device Table preview from a .nsm master.' It specifies the output format and distinct tabs, distinguishing it from sibling tools like export_diagram and export_master_xlsx.

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 explicitly states a prerequisite: 'call get_ai_context(master) (or at least get_network_state(master)) once per session.' This provides clear when-to-use context. However, it does not mention scenarios where the tool should not be used or suggest alternatives beyond the prerequisite.

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. It details behavior for each parameter, including edge cases: L2 PPTX area=None not supported, unknown areas rejected with clear error, and file naming conventions. It also mentions the return value is a summary and recommends using get_workspace_info to enumerate files. Missing are authentication or rate limit notes, but overall transparency is high.

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 lengthy but well-structured with clear headings and bullet-like formatting. Every sentence adds value, covering prerequisites, parameter details, edge cases, and return hints. It could be slightly more concise, but the structure aids readability.

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 (4 parameters, nuanced area behavior, output format differences, no annotations), the description is highly complete. It explains return values, file naming, and error handling. The presence of an output schema complements the description, but the description itself covers all necessary 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 description coverage is 0%, so the description must compensate. It does so thoroughly: explains master, layer, format (with SVG vs PPTX tradeoffs), and area (with detailed per-layer behavior for omitted vs provided area). This adds significant meaning beyond the bare schema 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?

The description explicitly states it exports an L1, L2, or L3 network diagram for a given .nsm master. It distinguishes from sibling export tools like export_device_table_html and export_master_xlsx by specifying the resource type. The verb 'Export' and resource 'network diagram' are specific and 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 clearly states a prerequisite: must have called get_ai_context(master) or get_network_state(master) beforehand. It also advises understanding which layer is meaningful given the network state. While it doesn't explicitly state when not to use or list alternatives, the context is clear enough for proper usage.

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

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

With no annotations, the description carries full burden. It states the .nsm is not modified and returns a result/error. However, it does not disclose potential issues like file size, permissions, or overwriting behavior, which could affect agent decision-making.

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 clear sections (Args, Returns). Every sentence adds value with no redundancy.

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

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

For a simple tool with one parameter and no annotations, the description sufficiently explains core behavior, input, and output. The presence of an output schema (though not elaborated) is acceptable. Lacks edge cases but adequate.

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?

Despite 0% schema description coverage, the description adds meaningful context for the 'master' parameter with an example ('[MASTER]office.nsm') and clarifies it is within the working directory. This goes beyond the schema's mere string type.

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 converts .nsm to .xlsx for offline use. It specifies the verb 'convert' and resource 'master'. However, it does not differentiate from sibling export tools like export_device_table_html or export_diagram, which lower the score slightly.

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 for when to use (Excel/offline edition) and where output goes, but lacks explicit when-not-to-use or alternatives. No mention of prerequisites or limitations.

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

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

With no annotations, the description bears full responsibility for behavioral transparency. It mentions using `--accept-security-risk` to bypass interactive prompts, which is good. However, it does not disclose whether the generated file persists, if any resources are modified, or potential side effects like overwriting. Safety and mutation traits are not fully addressed.

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 (about 5 sentences) and well-structured with a clear overview followed by parameter and return details. Every sentence adds value, though the example could be integrated more tightly. No redundancy.

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

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

Given no annotations and an output schema exists (implied), the description explains what the output contains and its purpose. However, it omits details like naming conventions, potential errors beyond a generic error message, and behavior upon repeated calls. It is functional but not exhaustive for a read-like operation.

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%, so the description must compensate for the single parameter `master`. It provides format guidance ('Master filename inside the working directory') and an example value. This adds meaningful context beyond the schema's bare name. No further details on validation or constraints are needed.

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 generates and returns the full AI Context file for a master. It specifies what the file contains (network state and CLI command reference) and that it invokes an internal command. While it distinguishes from siblings like get_network_state and export_master_xlsx by focusing on AI Context, it could be more explicit about uniqueness.

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 when an AI Context file is needed for planning multi-step edits, but it lacks explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though sibling tools exist for other export functions. The guidance is adequate but not thorough.

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?

It discloses that show commands are run and results are concatenated stdout. It references a config file for command list. No annotations exist, so the description adequately covers behavior, though more detail on read-only nature could help.

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 yet comprehensive, structured with a summary, details, and formal Args/Returns sections. Every sentence adds value.

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

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

Given the single parameter and no annotations, the description covers purpose, usage, parameter, and output format completely. It references an output schema which reduces need for return value details.

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

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

The description provides a detailed explanation of the 'master' parameter including format and example, far beyond the schema's minimal title. Schema coverage is 0%, but the description fully compensates.

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 the standard set of show commands and return aggregated results' and positions itself as 'the lightweight alternative to get_ai_context', distinguishing it from a sibling 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 explicitly contrasts with get_ai_context, implying this tool is for lighter queries. It lacks explicit when-not-to-use guidance but provides clear context.

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

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

No annotations provided, so the description carries the burden. It explicitly says 'always safe to call' and details return format and behavior when no workspace, offering good transparency.

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

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

The description is reasonably concise and front-loaded with purpose, but the inline return specification could be slightly trimmed or moved to an output 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 parameters and no annotations, the description fully covers behavior, return keys, and even a hint about a sibling tool, making it highly 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?

No parameters exist, baseline is 4. The description adds value by explaining the tool's purpose and return structure, though no parameter details needed.

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 returns the active workspace and list of .nsm master files, distinguishing it from sibling tools like suggest_workspace.

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 notes it's always safe to call and suggests using suggest_workspace when no workspace is active, providing clear context though not comparing to all 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?

No annotations are provided, so the description carries the full burden. It discloses that the original .xlsx is left untouched (non-destructive) and explains file naming behavior. However, it lacks details on error conditions, permissions, or what happens if the output file already exists. The description is adequate but could be richer given no annotations.

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

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

The description is 8 sentences, well-structured with a clear lead sentence, then usage context, then parameter details, then return value. It is concise for the information provided, with no redundant or verbose phrasing. A minor improvement could be grouping the parameter details more tightly.

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 2 parameters (1 required) and an output schema, the description covers the main action, usage scenario, parameter constraints, and return type. It lacks details on error handling or side effects beyond non-destructiveness, but this is acceptable for a simple conversion tool.

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

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

Schema description coverage is 0%, but the description adds significant meaning: xlsx_path requires absolute path, existence, .xlsx extension, and can be outside working directory; target_name must follow the naming convention '[MASTER]' and '.nsm' and defaults to source basename. This goes well beyond the schema's property titles and default, making parameters self-documenting.

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

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

The description clearly states the tool's purpose: 'Convert an existing .xlsx master into a .nsm in the working directory.' It uses a specific verb ('Convert') and resource ('xlsx master to .nsm'), and distinguishes from sibling tools like export_master_xlsx (reverse operation) and create_empty_master (creation from scratch).

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 advises use 'once at the start of a session' and explains that the Local MCP edition operates on .nsm files exclusively, so this tool bridges the gap. It does not explicitly list when not to use it or name alternatives, but the sibling context and the opposite action (export_master_xlsx) provide implied guidance. The explanation is clear but could be more explicit about 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?

Describes parsing of each line with shlex, invocation as single CLI command, and automatic appending of '--master'. It lists allowed verbs (add, rename, delete, show) and excluded export. Though no annotations exist, the description covers the execution behavior well, though it lacks explicit mention of destructive potential or error handling.

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

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

Description is front-loaded with purpose and prerequisite. While slightly long, each sentence adds value, and the example helps. Structured with Args and Returns sections. Could be more concise but overall efficient.

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

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

Given no annotations and the presence of an output schema, the description adequately covers input parameters, prerequisite, allowed verbs, and return format. It is fully sufficient for an agent to use the tool 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?

Schema coverage is 0%, but the description adds full meaning: 'Master filename inside the working directory' for master, and 'Newline-separated CLI command lines' with an example for commands. This provides complete semantic understanding beyond the raw schema.

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

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

The description explicitly states 'Execute one or more Network Sketcher CLI commands against a .nsm master,' clearly specifying the verb (execute) and resource (CLI commands on .nsm master). It distinguishes from sibling tools by listing allowed verbs and explicitly excluding 'export', which directs to sibling 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?

Provides explicit prerequisites ('MUST have called get_ai_context...'), explains why the prerequisite is necessary, and gives clear when-to-use and when-not-to-use guidance by listing allowed verbs and excluding 'export'. Also warns not to include '--master' argument.

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 fully discloses behavioral traits: validation against home directory, creation if missing, writable check, and the session-scoped persistence. This is clear and sufficient for safe use.

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

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

The description is concise, with no wasted sentences. It uses a structured format with Args and Returns sections, making it easy to parse.

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 single parameter, no annotations, and presence of an output schema, the description provides complete context including validation, creation, writability, and return value description.

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%, so the description compensates by explaining the 'path' parameter: it must be absolute, supports '~' for home expansion, and must resolve under Path.home(). This adds essential 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 description clearly states the action: 'Set the active workspace directory for this session.' It specifies a verb (set) and resource (workspace directory), and the purpose is distinct from sibling tools like get_workspace_info and suggest_workspace.

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

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

The description explains the lifecycle of the workspace setting and that subsequent calls operate against this directory. It does not explicitly state when not to use it, but the context implies its role relative to get_workspace_info.

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 exist, so the description must fully disclose behavior. It states the tool returns candidate paths with hints, is safe to call, and describes the output structure. However, it could mention potential side effects or edge cases, but for a suggestion tool, this is sufficient.

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 appropriately sized and front-loaded with purpose. It is clear and to the point, though the mentioned return structure could be placed earlier for even better structure. No unnecessary 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?

Given the tool has no parameters and an output schema described in text, the description covers all necessary aspects: purpose, safety, workflow, and return format. It references sibling tools and provides complete context for an agent to use it 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 are no parameters, so the description adds all meaning beyond the empty schema. It explains the tool's purpose and return format, meeting the baseline for 0 parameters. The description could be slightly more detailed about the output keys, but it is adequate.

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 uses the verb 'Suggest' and specifies the resource 'OS-appropriate workspace directory candidates'. It distinguishes itself from sibling tools like set_workspace by outlining the workflow, making the purpose 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?

Explicit guidance is provided: 'Always safe to call', the workflow of proposing one candidate and seeking confirmation before calling set_workspace, and noting that custom paths are acceptable. This leaves no ambiguity about when and how to use the tool.

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