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

With no annotations, the description carries the behavioral transparency burden. It usefully discloses that this is 'best-effort UI automation' and advises confirming the dialog if nothing appears. However, it does not mention side effects such as file overwriting, what happens if Bizagi is not open, or whether the operation mutates the diagram.

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 the main action. The purpose, automation caveat, and parameter explanation are each given in a compact sentence, with no wasted words.

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

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

Given the tool's single parameter and the presence of an output schema, the description covers the core requirements: exact action, prerequisite, output destination, and a behavioral caveat. It could add more failure-mode detail, but nothing essential is missing for making the call.

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

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

Schema coverage is 0%, so the description must explain the parameter. It does: 'output_path: Where Bizagi should write the .bpmn file.' This adds meaning beyond the schema title 'Output Path' by indicating the intended destination and file 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?

Description states a specific UI command ('Drive File ▸ Export ▸ BPMN') and the resource ('diagram currently open in Bizagi Modeler'), plus the downstream purpose ('read and audited by other tools'). This clearly distinguishes it from sibling tools like bizagi_import_bpmn and export_documentation.

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 context: it applies to the diagram currently open in Bizagi Modeler and is meant to make the BPMN available for other tools. It does not explicitly name alternatives or say when not to use it, but the intended scenario is clear enough.

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 behavioral burden. It openly states 'Best-effort UI automation', warns that ribbon shortcuts differ between Modeler versions, and instructs manual fallback if it fails. It doesn't describe side effects or expected post-import state, but this is notably honest for a UI-automation 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?

Three short sections with front-loaded purpose; every sentence contributes a distinct fact: purpose, caveat, fallback, and parameter. There is no filler or repetition of schema fields.

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 one-parameter tool, the definition covers the action, parameter, and failure mode, and an output schema exists for return values. However, it omits prerequisites such as Bizagi Modeler already being open or a target process being active, which an agent may need to sequence with sibling tools like bizagi_open or bizagi_status.

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 'file_path: The .bpmn file to import' line is the only parameter guidance. It adds the .bpmn extension and import purpose to the schema's bare string, though it does not detail path format or existence requirements beyond the earlier 'already on disk' note.

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 an explicit verb ('Drive') and resource ('Bizagi Modeler's File ▸ Import ▸ BPMN dialog for a .bpmn file'). It unambiguously identifies an import operation, which distinguishes it from sibling export/open/read tools by UI route.

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 no explicit 'use when ... not when ...' guidance or alternatives among sibling tools. It does provide a manual fallback and a caveat about version differences, which implies best-effort usage, but it doesn't address when to prefer this over siblings like bizagi_export_bpmn or bizagi_open.

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, and it does disclose the key behavior: it launches the desktop app, optionally opens a .bpm/.bpmn file, and treats an empty file_path as 'just start the application.' It does not cover failure modes or return behavior, but for a non-destructive open action the disclosed behavior 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 compact and front-loaded: it states the action in the first sentence, adds one clarifying behavioral sentence, and then gives a precise Args section. There is no unnecessary filler or repetition of schema info.

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 one-parameter desktop launcher, this is complete: it covers the optional file path, accepted extensions, the behavior when empty, and the invocation method. Since an output schema exists and no annotations are present, there is nothing essential missing for an agent to call this 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?

The schema provides no description for file_path, but the description fully compensates: it explains that file_path is the diagram to open, accepts .bpm or .bpmn files, and explains the empty-string behavior. This adds real semantic value 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 opens with a specific verb and resource: 'Open Bizagi Modeler,' and adds the optional file types .bpm or .bpmn. It is unambiguous, but it does not explicitly differentiate this tool from siblings like bizagi_import_bpmn or bizagi_export_bpmn by name.

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 the tool by calling it 'the dependable desktop action' and explaining that the file is passed via the command line, but it does not state explicit when-to-use or when-not-to-use conditions. It also does not name alternative sibling tools that might be better suited for import/export or process-read tasks.

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 whether' makes the read-only nature reasonably clear, and the listed checks describe what the tool does without side effects. It could be more explicit about not modifying anything, but the wording strongly implies a diagnostic operation.

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 one focused sentence that front-loads the purpose ('Report whether Bizagi Modeler can be controlled from here') and then lists the specific facts it reports. The final instruction is a clear directive with no wasted words.

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

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

For a zero-parameter status tool with an output schema, the description is complete: it states what is checked, signals read-only behavior, and tells the agent to call it before siblings. Nothing essential is missing 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 description cannot add parameter-level meaning. Per the rubric, a 0-parameter tool gets a baseline of 4 because parameter semantics are not applicable.

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 the verb 'Report' with a specific resource (Bizagi Modeler controllability) and enumerates the exact status items checked: platform, pywinauto availability, exe location, running state, and open document. This clearly differentiates it from the action-oriented 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?

The description gives explicit usage guidance: 'Call this before the other bizagi_* tools.' This tells the agent when to invoke it in a workflow. It does not mention exclusions, but for a status/preflight tool, the sequencing instruction is sufficient.

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 handles it well: file writing, preview-only mode when output_path is empty, overwrite replacement semantics, large return_xml payloads, and formatting/layout behavior are all 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 main purpose is front-loaded, followed by compact behavior notes and a terse argument list. Every sentence adds operational value without 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 complex spec-object tool with no annotations, this is unusually complete: input format source, output behavior, preview mode, overwrite safety, response-size tradeoff, and audit result are all covered. The output schema handles the remaining return-shape 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?

Schema description coverage is 0%, and the description compensates fully: spec is tied to get_spec_reference(), output_path explains preview behavior, overwrite explains replacement, and return_xml warns about large responses. This adds far more meaning than the bare schema properties.

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 action and artifact: 'Generate a BPMN 2.0 diagram from a process specification and write it as a .bpmn file.' It further differentiates from siblings by naming Bizagi Modeler import, making it distinct from list/update/read/validate/render 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?

It gives clear operational context: call get_spec_reference() for the spec format and leave output_path empty to preview. However, it never explicitly states when to choose this tool over siblings like render_preview, validate_process, or bizagi_import_bpmn, so alternatives are left to inference.

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

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

With no annotations, the description carries the behavioral burden and does a good job: it discloses file-writing behavior, the 'return text only' mode when output_path is empty, the effect of overwrite, and the optional audit append. It stops short of covering error cases or side effects, but the main behavior is transparent.

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

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

The description is compact, front-loaded with the core purpose, and uses a clean Args block. Every sentence adds information; there is no filler or repetition of schema fields.

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 no annotations, the description covers purpose, all parameter semantics, and output behavior. It is slightly less explicit about return details or edge cases, but the presence of an output schema and the detailed parameter notes make it sufficiently complete 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 fully compensates by explaining every parameter: file_path, output_path including empty-string behavior, include_audit, and overwrite. Each gets a meaningful semantic beyond its name or 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 opens with a specific action and object: 'Produce a Markdown process document from a .bpmn file', and enumerates the document's contents (pool/lane outline, step-by-step flow, optional audit findings). This makes it easy to distinguish from siblings such as validate_process or render_preview 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 purpose statement clearly implies the use case: generate Markdown documentation from an existing BPMN file. It does not name alternatives or explicitly state when not to use it, but the context is clear enough that an agent can infer when to invoke 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 itself must signal behavior. 'Show' clearly indicates a read-only lookup, and 'Read this before...' frames it as a non-mutating prerequisite step without side effects. It doesn't discuss auth or rate limits, but a static reference tool has no such concerns.

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 the core purpose front-loaded and the usage directive in a natural second sentence. Every word contributes; no wasted 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 zero-parameter reference tool with an output schema, the description says what it returns, what it concerns (create_process spec format), and when to use it. Nothing needed to invoke it correctly is missing.

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

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

The tool accepts zero parameters, so the baseline for this dimension is 4. The description explains what the returned reference will cover rather than parameters, which is appropriate for a parameterless call.

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?

Description identifies a specific action ('Show the specification format'), the exact resource (the format create_process expects), and the content scope (node types, fields, modeling rules). This clearly sets it apart from sibling tools like create_process, update_process, and read_process.

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?

Tells the agent precisely when to invoke it: 'Read this before writing a spec for the first time.' It does not list exclusions or alternative reference tools, but none of the siblings fill this exact role, so the guidance is sufficient.

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 behavioral burden and does disclose that only .bpmn files receive a one-line summary covering pools, activities, and gateways. However, it does not state whether the operation is read-only, how Bizagi files are treated beyond being found, or how empty folders or invalid directories behave.

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

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

The description is two short, front-loaded sentences followed by compact Args lines. Every sentence adds information, and there is no redundant restatement of the tool name or schema.

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

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

For a simple two-parameter discovery tool with an output schema present, the description covers purpose, scope, summary behavior, and parameter meaning. Minor gaps remain around Bizagi file handling and edge cases, but nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate; the Args block adds meaning by defining directory as 'Folder to scan' and recursive as 'Include sub-folders'. This fully disambiguates both parameters for a simple tool, though it does not explain expected file formats or path encoding.

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

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

The description states a specific action ('Find') and resource ('BPMN and Bizagi files in a folder'), and distinguishes the tool from process-editing siblings by emphasizing folder scanning and one-line summaries. It is immediately clear what the tool does and how it differs from read_process or validate_process.

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 purpose implies usage when an agent needs to discover or summarize BPMN/Bizagi files in a directory, but the description never explicitly states when to prefer this over sibling tools or when not to use it. There are no exclusions or alternative routing cues for the agent.

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 behavioral burden and does well: it discloses supported file types (.bpmn/.xml), an explicit unsupported format (.bpm), and the meaning of each detail mode. It does not explicitly state it is read-only, but the verb 'Read' and the absence of side-effects language make the behavior reasonably clear.

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, a short necessary limitation note, and a clear Args section. No filler or redundant restatement of the tool name.

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 operation with an output schema present, this description covers supported formats, the key unsupported format, parameter semantics, and the relationship to create_process. Nothing essential for an agent to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It does: file_path is explained as 'Path to a .bpmn or .xml file', and detail enumerates all three options with their semantic meaning, including how 'spec' can be passed back to create_process.

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

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

States a specific verb ('Read'), a concrete resource (.bpmn file), and the return structure (pools, lanes, activities, gateways, events, flows). It clearly distinguishes read_process from sibling tools that list, create, update, or import processes.

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

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

Gives clear context on when to use the tool and an important prerequisite: Bizagi's native .bpm format must be exported to BPMN first. It does not explicitly contrast with sibling tools like validate_process or list_processes, but the included create_process reference in the detail parameter adds useful routing 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?

With no annotations, the description carries the full behavioral burden. It discloses the write behavior (output_path, overwrite), the alternate return mode (returning markup when output_path is empty), and the promise that geometry matches the .bpmn. This is strong and decision-relevant 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 compact and front-loaded: a two-sentence purpose statement followed by a clean argument list. Every sentence earns its place and the structure is easy for an agent to scan.

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 output modes, overwrite behavior, and all parameters, and an output schema exists. The main gap is that, with zero required parameters and both file_path and spec defaulted, the description never explicitly states that one of them must be supplied.

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%, and the description fully compensates by explaining all four parameters with functional meaning: .bpmn file input, an in-memory spec, output location with fallback behavior, and overwrite semantics. The mutual-exclusivity note adds important semantic value 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 opens with a specific action ('Draw the diagram as an SVG') and a clear purpose ('checked without opening Bizagi Modeler'). It is specific about the resource and output format, but it does not explicitly differentiate from sibling tools like bizagi_import_bpmn or export_documentation.

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

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

It gives a clear use case — verifying a diagram before import via 'what you see is what imports' — and notes that file_path and spec are mutually exclusive. It does not explicitly state when to prefer this tool over related siblings or when not to use it, so it stops short of a top-tier score.

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 behavioral disclosure burden. It discloses the merge semantics, id-based replace-vs-append behavior, removal keys, fresh layout regeneration, and overwrite behavior. It does not cover failure modes or explicitly state what happens to omitted spec fields, but overall transparency is strong.

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: core edit/regenerate behavior comes first, followed by merge rules and a terse args list. Every sentence earns its place, and the overwrite safety note is compact but important.

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 four parameters and the free-form nested changes object, the description is largely complete, and the output schema exists so return values need not be explained. It would be more complete if it defined 'spec' or pointed to get_spec_reference, since 'same keys as a spec' assumes vocabulary the agent may not already have.

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%, yet every parameter is meaningfully documented: file_path identifies the target, changes is explained as a partial spec with merge/deletion semantics, output_path specifies destination and default behavior, and overwrite is clarified as required for existing files. This fully compensates for the bare 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 opens with a concrete verb and resource: 'Edit an existing .bpmn file', and adds the distinctive behavior of merging changes and regenerating the diagram. This clearly separates it from siblings like create_process, read_process, and validate_process even without naming them explicitly.

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

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

The description establishes clear context: this is for editing an existing BPMN file, not creating or reading one. It also provides a practical condition, stating that overwrite is required when writing over an existing file. It does not explicitly list alternatives or exclusions, which prevents a 5.

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

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

No annotations are present, so the description carries full responsibility. It discloses the audit scope (checks listed), the two input modes and their mutual exclusivity, and the format options. However, it does not explicitly state whether the tool is read-only (though implied) nor mention any permissions or side effects. For a validation tool, this is a moderate gap.

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 starts with a clear one-sentence purpose, then details the checks, and ends with parameter explanations. It is front-loaded and structured well. The list of checks is lengthy but informative, and the Args block is efficient. Some redundancy exists (e.g., the purpose sentence and the check list both mention correctness), but overall it is concise relative to 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?

For a complex auditing tool with an output schema, the description covers the main aspects: purpose, checks performed, input modes, and format selection. It does not describe return structure, but the presence of an output schema reduces that need. Missing details like error handling or behavior on invalid input are not critical for this tool type, making the description reasonably 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%, but the description's 'Args' section explains all four parameters: file_path, spec, include_best_practice, and format. Each has a brief explanation, and the mutual exclusivity of file_path and spec is noted. The spec explanation ('A specification to audit before generating it') is slightly vague, but overall the description compensates well for the missing schema descriptions.

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

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

The description clearly states the tool audits a diagram against BPMN 2.0 rules and returns findings with fixes. The verb 'Audit' is specific, the resource is a BPMN diagram, and it is distinct from siblings like list_processes, create_process, or render_preview. No sibling performs validation, so purpose is unambiguous.

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

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

The description implies usage context—auditing a diagram for correctness—and differentiates from generation tools. However, it never explicitly says 'use this when you need to validate' or contrasts with alternatives like read_process. The purpose is so specific that an agent can infer when to use it, but no exclusions or conditional guidance are given.

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