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

With no annotations, the description carries the full burden. It usefully discloses invariants — the operation's method must exist on the receiver class/superclass/interface, return messages must target an active object, and replace_existing deletes same-named diagrams first. However, it never explains the copy semantics (does source_path get copied to output_path?), what overwrite_output does, or what happens on validation failure.

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?

Purpose is front-loaded, and the JSON example earns its space given the complex nested structure. But the opening is redundant ('Dodaje diagramy sekwencji... Dodaje całe diagramy sekwencji'), and the dense inline comments inside the example require careful parsing rather than being stated as separate rules.

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 high-complexity batch-mutation tool, the description covers the hardest part (the diagram data model) thoroughly, and an output schema exists so return values needn't be explained. The remaining gap is the unexplained file-path parameters and overwrite_output, which keeps it from a 5.

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

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

Schema coverage is 0%, so the description must compensate. It does an excellent job documenting the inner structure of the 'diagrams' parameter (participants, item types call/self/create/return/found/signal/loop/opt/alt/ref), but source_path, output_path, and overwrite_output receive no explanation at all. Partial compensation for a low-coverage 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 ('Dodaje diagramy sekwencji do kopii projektu'), which distinguishes it from the delete/get sequence-diagram siblings by name. It doesn't explicitly state the distinction from vpp_edit_class_model or vpp_export_plantuml, but the operation 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?

Usage is only implied: add diagrams to a project copy. There is no explicit 'use this when...' guidance, no mention of what to do instead for modifying existing diagrams, and no statement of prerequisites for source_path/output_path. The only conditional guidance is the replace_existing=true behavior.

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 does credibly disclose that the delete is cascading (diagram plus frame, participants, messages, fragments) and that a ref-based reference blocks it. It does not state whether the removal is permanent or recoverable, nor how output_path and overwrite_output govern the write, which matters for a destructive 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?

Two tight sentences: the destruction scope first, the failure precondition second. No filler, and the most decision-relevant information is front-loaded, though the meaning would be more accessible if the language matched the English tool and parameter names.

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?

A return schema exists, so return values need not be explained. However, for a four-parameter destructive tool with zero annotation coverage, the description leaves the copy/output path semantics and the irreversibility question unanswered, which is a meaningful gap even though the cascade and refusal behavior are covered.

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 all four parameters are bare titles, yet the description explains only that a diagram is deleted by name. 'W kopii projektu' faintly gestures at the source/output split but says nothing about source_path, output_path, or when overwrite_output must be true — the description fails to compensate for the coverage gap.

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?

Names a specific verb and resource ('Usuwa diagram sekwencji') and enumerates the exact scope of removal (ramkę, uczestników, komunikaty, fragmenty), so the agent knows the blast radius without opening the schema. It is clearly the destructive counterpart to siblings like vpp_get_sequence_diagram and vpp_add_sequence_diagrams, though it never names 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 refusal condition ('Odmówi, jeśli inny diagram odwołuje się do niego przez ref') is a genuine usage constraint that tells the agent this call can fail for referential reasons. The phrase 'w kopii projektu' hints the operation targets a copy rather than the original, but there is no explicit guidance on when to use this versus re-editing a diagram, nor on how the copy workflow should be sequenced.

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 zero annotations the description carries the full burden, and it does substantial work: non-destructive output-to-new-file, atomic transaction semantics, sequential ordering, conditional refusal on remove_member, ID preservation in change_operation keeping sequence-diagram messages valid, and side effects for move_class (relation lines recomputed) and fit_class (box resized). Remaining gaps are the source_path/output_path/overwrite_output behaviors and error/partial-failure reporting, but the mutation surface is well 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?

Front-loaded with purpose and a one-line atomicity rule, then a dense bullet-per-operation reference rather than prose. It is long, but nearly every line encodes syntax an agent could not otherwise infer (op names, field names, override semantics); the closing type and visibility glosses are worth their space.

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 multi-op mutation tool with an output schema, the description covers the operation vocabulary, ordering, atomicity, and key side effects well. It stops short of describing the source_path contract, overwrite_output behavior, or what a rejected batch reports back, which an agent would want before a first 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 description coverage is 0%, so the description must compensate, and it does so heavily for the dominant parameter: every 'op' variant is enumerated with field-level meaning, direction conventions for generalization/realization/dependency/aggregation, allowed type names, and visibility syntax. The three path/overwrite parameters are only implicitly addressed ('wynik do NOWEGO pliku') and overwrite_output is never explained.

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?

Opens with a specific verb+resource pair ('Zmiany w modelu klas i na diagramie klas') and immediately adds the key distinguishing scope: the result goes to a NEW file with the original untouched. This clearly separates it from read-only siblings like vpp_get_class and vpp_list_classes without needing to name them.

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 strong operational context: changes are applied in order and are all-or-nothing, and remove_member refuses when a message still calls the method. What it lacks is any explicit routing versus alternatives (e.g., when to use change_operation vs remove_member+add_operation), leaving that to inference from the genre of the tool.

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

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

With no annotations, the description carries the full burden: it does disclose a real behavioral rule (relationships are only included between selected classes), which is valuable. However, it never says that the required 'path' means writing/overwriting a file on disk, nor anything about permissions or side effects — critical for a tool that appears to produce output at a path.

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?

Compact and front-loaded: the export action and PlantUML target come first, followed by the use case and the class-filtering note. No filler sentences, though the parameter notes read as a slightly tacked-on tail.

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?

An output schema exists, so return-value explanation is not required. Still, for a tool whose only required parameter is a destination path, the omission of what happens at that path (file creation, overwrite, encoding) leaves a meaningful gap.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'classes' well (list of class names, defaults to all) but leaves the required 'path' and the 'with_members' flag (default true) entirely unexplained, so only one of three parameters gains 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?

Names a specific verb and resource (export a class-diagram fragment to PlantUML) and adds a concrete scenario (before/after pattern study). No sibling tool performs PlantUML export, so the purpose is distinguishable, though the description never explicitly contrasts itself with siblings like vpp_list_classes or vpp_get_class.

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 before/after pattern-study example implies when to reach for this tool, but there is no explicit when-not guidance and no mention of alternatives for simply inspecting classes (vpp_list_classes/vpp_get_class). Usage is implied rather than stated.

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 supplied, so the description carries the burden; it does convey that this is a read operation returning a rich composite view (members, relationships, diagram positions). However, it says nothing about behavior on a non-existent class, permission/auth needs, or whether the relationship data is expensive to compute.

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

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

One compact sentence that front-loads the resource and then lists the returned facets. Nothing is wasted, though the enumerated facets overlap with what the output schema already conveys.

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?

Because an output schema exists, the description need not explain return values, so the main remaining gap is the undocumented 'path' parameter and the absence of any error/precondition guidance. Adequate but not fully sufficient for a two-required-parameter lookup 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% for both required parameters. The description implies that 'name' identifies the class, but the required 'path' parameter is never explained (project path? file path? diagram path?), which is the main ambiguity an agent would hit. Only half the parameters gain any meaning beyond their bare names.

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?

Names a specific resource (one class) and enumerates what the result contains: kind, members, all relationships it participates in, and placement on class diagrams. This clearly distinguishes it from the sibling vpp_list_classes, which returns many classes. It falls short of 5 only because it never explicitly names the sibling it complements.

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 phrasing 'jednej klasy' (a single class) implies this is the drill-down tool after listing, but no explicit when-to-use or when-not-to-use guidance is given. An agent must infer that it should call vpp_list_classes first to obtain the name/path.

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 supplied, so the description carries the full behavioral burden, yet it says nothing about whether the call is read-only, what permissions or project context are needed, or what happens when the named diagram does not exist. Its content is essentially a description of the returned payload, which is already covered by the declared output schema, so it adds little behavioral value beyond structured fields.

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?

It is a single compact sentence with the key noun front-loaded, so there is no padding. However, it spends its limited words enumerating output fields instead of the call's purpose, and the Polish text is inconsistent with an otherwise English tool/sibling vocabulary.

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

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

The tool has an output schema, so return values need not be explained, but with two required undocumented parameters and no annotations, the description should at minimum explain what path and name refer to and what a failed lookup yields. It omits both, leaving invocation details underspecified.

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% for two required parameters (path, name), and the description never mentions either one — it does not clarify whether path is a project path or a file path, nor how name identifies the diagram. With full documentation responsibility falling on the description and nothing provided, this is a clear gap.

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

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

The description names the resource ("diagram sekwencji") and implies retrieval by saying it is an "opis" (description) of that diagram, but never states the verb explicitly (get/read/return) and gives no differentiation from siblings such as vpp_add_sequence_diagrams, vpp_delete_sequence_diagram, or vpp_export_plantuml. An agent can guess it reads a diagram, but must infer that from the tool name rather than the text.

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

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

There is no when-to-use guidance, no exclusions, and no mention of the closely related siblings (add/delete sequence diagram, export to PlantUML). The agent is left to infer that this is the read counterpart to the mutating siblings purely from naming conventions.

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 supplied, so the description carries the full burden. 'Lista' implies a read-only operation and the with_members flag's effect is disclosed with real output examples, but nothing states permission requirements, whether the scan is recursive across the .vpp file, or anything about result size.

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 tightly written sentences that front-load the resource list and follow with the only optional flag. Nothing is redundant, though the abrupt switch from Polish prose to the English parameter name and back is slightly jarring.

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?

An output schema exists, so return values need no explanation, and the with_members behavior is well covered. For a two-parameter tool the missing pieces are the meaning of the required path argument and the read-only/scope guarantees, which an agent still has to guess.

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, and it does so well for with_members, spelling out the UML notation it triggers with concrete samples like '-email : String'. The required 'path' parameter, however, is never explained - it is unclear whether it points at a .vpp file, a directory, or a project selector.

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

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

The description names a specific verb (list) and enumerates the exact resource types returned: classes, abstract classes, interfaces and enumerations. That is enough to distinguish it from the singular vpp_get_class and from vpp_list_relationships, though it never names those siblings 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?

It explains when to set with_members=true (to also get attributes, methods and enum values), which is genuine usage guidance for the parameter. It gives no guidance on when to choose this tool over vpp_get_class or vpp_list_relationships, so tool-selection context is only implied.

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 usefully discloses that every relationship carries an id needed for deletion (implying a follow-up delete workflow) but says nothing about permissions, ordering, or the meaning of 'path' (presumably a .vpp project file).

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 front-loaded with the output's shape in notation terms, then the id note, then the filter. It is dense but every clause carries information; the notation enumeration is long but genuinely distinguishes relationship types.

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?

An output schema exists, so return structure needn't be re-explained, and the relationship-kind enumeration covers semantics well. The main gap is the undefined required 'path' parameter, which an agent cannot resolve from schema or description alone.

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 class_name as a filter narrowing to one class's relationships, but leaves 'path' completely undefined – the agent must infer it is the project file path.

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 the specific verb+resource (listing relationships) and enumerates the relationship kinds in PlantUML notation (generalizations, realizations, dependencies, associations with multiplicities/roles). This clearly distinguishes it from siblings like vpp_list_classes or vpp_get_class, though it never names a sibling 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?

It implies usage through 'each has an id (needed for deletion)' and 'class_name narrows to a given class''s relationships,' which hints at pre-deletion discovery and filtered listing. However, there is no explicit when-to-use/when-not guidance versus alternatives such as vpp_export_plantuml or vpp_get_class.

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, "Podsumowanie" only implies a non-mutating inspection and does not explicitly confirm that the project is left unchanged. It also leaves unclear whether the tool parses the file directly or interacts with VP, and whether an already-open file affects execution.

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

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

The description is a single compact, front-loaded statement with no filler. Its enumerated details all help establish the tool's scope.

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 one-parameter tool with an output schema, the description is largely sufficient to understand the requested operation. The undocumented path semantics and unclear file/VP interaction and safety behavior remain meaningful invocation 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?

The schema gives the required path parameter no description, and the description only indirectly indicates that it should identify a .vpp project. It does not explicitly define path as the filesystem path to an existing project file or clarify any path-handling expectations.

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 identifies the tool as providing a .vpp project summary and enumerates its scope: diagrams, model-element counts, actors, use cases, relationships, and whether the file is open in VP. It does not explicitly distinguish this broad overview from the sibling list and detail 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 listed contents imply that the tool is intended for a high-level project overview rather than detailed retrieval of individual model elements. However, it provides no explicit when-to-use guidance or alternatives such as vpp_list_classes, vpp_list_relationships, or vpp_get_sequence_diagram.

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 supplied, so the description carries the full behavioral burden. It establishes that this is a check, but does not state whether it is read-only, whether it repairs or writes back to the file, whether it can fail hard versus return findings, or what permissions/access the path requires. The "always passes" note is a helpful behavioral clue but far from complete for a mutation-ambiguous tool with zero annotation coverage.

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

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

Two short sentences, front-loaded with the operation and its scope, with the caveat about VP-saved files second. No redundant restatement of the name and no filler.

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

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

With a single required parameter, an existing output schema, and no annotations, the description covers the essential question of what the tool inspects. The remaining gap is behavioral: whether verification has side effects on the file and how it relates to vpp_project_info, which the agent must guess.

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 (path) with 0% schema description coverage, so the description should compensate. It does so minimally by tying the input to a .vpp file, telling the agent what kind of path to supply, but says nothing about relative vs absolute paths, whether the file is modified in place, or error behavior for a non-.vpp file.

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?

"Strukturalna kontrola pliku .vpp" gives a clear verb (kontrola/walidacja) and resource, and the parenthetical enumerates exactly what is checked: references, IDs, model-view links, lists. It does not name or distinguish itself from any sibling, but the siblings (edit, delete, list, get, export) are operationally distinct, so misselection risk is low.

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

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

There is no explicit when-to-use or when-not-to-use statement against alternatives such as vpp_project_info. The second sentence, "Pliki zapisane przez VP przechodzą ją zawsze," implicitly signals the useful case (externally or programmatically modified files) and that native exports will be clean, but the agent must infer this rather than being told.

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