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

Beyond annotations (which already indicate non-read-only, non-destructive), the description adds critical behavioral details: rollback_on_error behavior, return envelope structure, and error types. No contradiction with 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 well-structured with sections for purpose, connection item details, Args, Returns, and Errors. Every sentence adds value, and it is front-loaded with the core action.

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 moderate complexity (3 parameters, output schema exists), the description covers all essential aspects: input, return fields, and error conditions. The presence of an output schema reduces the need for detailed return documentation, but the description provides it anyway.

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

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

The input schema has no descriptions (0% coverage), but the description fully explains each parameter, including the complex 'connections' item shape, default value and effect of rollback_on_error, and the syntax for field aliases.

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 adds multiple visual connections to a view, using a specific verb ('Add') and resource ('visual connections to a view'), distinguishing it from the sibling add_connection_to_view.

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 references the sibling add_connection_to_view by stating that each connection item supports the same fields, implying batch vs single usage. However, it lacks explicit 'when to use' or 'when not to use' guidance, though the context is clear.

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?

Discloses behavioral traits beyond annotations: connection_id uniqueness across entire active model (with namespace suggestion), required preconditions, and detailed error cases. Annotations indicate mutability but description adds specific mutation details without contradiction.

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?

Well-structured with Args, Returns, Errors sections. Front-loaded with core purpose. Slightly lengthy due to detailed uniqueness paragraph but all content is necessary and earns its place.

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

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

Complete for a mutation tool with 3 params and output schema mentioned. Covers preconditions, return value, error types, and unique constraint. No gaps found.

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 coverage, the description thoroughly explains all three parameters: view_id, relationship_id, and optional connection_id including uniqueness constraints and namespace recommendation. Adds significant meaning 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?

Clearly states 'Add a visual connection for a relationship in a view' – specific verb (add) and resource (connection) with scope. Distinguishes from sibling tools 'connect_visible_relationships' and 'add_node_to_view' by explaining preconditions and alternatives.

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 both endpoints must already be visible, and directs to use 'add_node_to_view' to add missing endpoints or 'connect_visible_relationships' as an alternative. Provides clear when-to-use guidance and 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?

Provides extensive behavioral details beyond annotations: describes element creation behavior, folder path normalization, element_id uniqueness constraints and collision rejection, and lists all four error conditions. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with the description's creation semantics.

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

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

The description is well-structured with clear sections for args, returns, and errors, and uses bullet-like formatting for readability. It is somewhat verbose but every sentence adds value; minor redundancy in error enumeration could be streamlined.

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 6 parameters, a rich output schema (described), and no gaps in usage or error documentation, the description is fully complete. Covers purpose, parameter details, return shape, and error conditions without leaving the agent guessing.

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?

With 0% schema description coverage, the description fully compensates: it explains each parameter's purpose, constraints (e.g., name must be non-empty), examples for element_type, normalization details for folder_path, and namespace advice for element_id. This is far beyond baseline given 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?

Clearly states the verb ('Add') and resource ('new ArchiMate element'), specifies the scope ('to the active model'), and distinguishes from siblings (e.g., 'add_elements' for batch, 'list_supported_types' for discovery) through explicit cross-reference.

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 advises using 'list_supported_types' when uncertain about element types, and explains how to use the returned ID for relationships and view nodes. However, lacks explicit when-not-to-use guidance (e.g., versus 'add_elements') and does not state the prerequisite of an active model directly, though errors hint at 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?

Annotations indicate readOnlyHint=false (write), destructiveHint=false, openWorldHint=false. The description adds critical behavioral context: rollback_on_error restores state, IDs are unique across the model, and error behavior stops at first failure. There is no contradiction with 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 well-structured with sections for description, args, returns, and errors. It front-loads key purpose details. It is slightly verbose with the element item shape example but remains focused and 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?

The tool has 2 parameters, no schema descriptions, but has an output schema mentioned. The description covers returns (data.elements, count, rollback_on_error) and specific error types. For a batch operation with rollback, this is a complete and self-contained 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 description carries full burden. It thoroughly explains the `elements` parameter structure, field aliases (type/element_type, id/element_id), required fields, and the `rollback_on_error` default. This adds substantial meaning beyond the schema's minimal definitions.

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

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

The description clearly states it adds multiple elements to the active model in one call. It distinguishes from the sibling tool `add_element` by noting it supports the same fields for each item but allows multiple items at once, making the purpose specific and distinguishable.

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 explicit guidance on ID uniqueness across the entire model, warning against reusing naming patterns across batches. It also mentions the rollback behavior and error handling. While it does not explicitly state when not to use this tool versus `add_element`, the context of batch addition is clear.

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?

Annotations indicate mutation (readOnlyHint=false) and non-destructiveness (destructiveHint=false). The description adds value by explaining the rollback_on_error behavior, the success envelope with node_ids and count, and specific error types (ModelOperationError, ElementNotFoundError). This goes beyond what annotations provide.

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 sentence, a bullet-like explanation of node shape, and separate sections for args, returns, and errors. It is relatively concise but could be tightened slightly; the node item shape example adds clarity without being overly verbose.

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

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

Given the tool's complexity (3 parameters, nested objects, output schema exists), the description covers purpose, parameters, returns, and errors. It implies the view must exist and handles failure modes. The output schema is mentioned, so return values are explained. It does not explicitly list prerequisites but is largely 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?

The input schema has 0% description coverage, so the description carries the full burden. It explains all three parameters: view_id (target view ID), nodes (list of node objects with shape details including optional/required fields), and rollback_on_error (default true). This adds significant meaning beyond 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 clearly states the verb 'Add multiple visual nodes to a view in one call,' specifying the resource (view) and the action (add nodes). It distinguishes from the sibling tool 'add_node_to_view' by being a batch variant and explains that each node supports the same fields. This provides clear purpose and differentiation.

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

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

The description implies that this tool is for adding multiple nodes in one call, contrasting with the single-node sibling. It mentions the rollback_on_error behavior and error handling, which provides context. However, it lacks explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

The description adds significant behavioral context beyond the annotations: overlap handling, default sizes, UUID generation rules, and error conditions. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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-organized with Args, Returns, Errors sections. It is detailed but not excessively verbose. Minor improvements could make the node_id uniqueness explanation slightly more concise.

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 7 parameters (0% schema coverage) and output schema presence, the description covers all inputs, returns, and errors thoroughly. No gaps remain for agent understanding.

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 explains every parameter's purpose, defaults, and behavior (e.g., x/y overlap, node_id uniqueness across the entire model). This fully compensates 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 action ('Add an ArchiMate element as a visual node in a view'), specifying both the verb and the resource. It distinguishes from sibling tools like 'add_element' (which adds to model) and 'add_nodes_to_view' (batch operation).

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 detailed guidance on positioning, defaults, and uniqueness constraints. While it doesn't explicitly state when not to use this tool, the context is clear from sibling names (e.g., for batch use 'add_nodes_to_view').

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?

Discloses extensive behavioral traits beyond annotations: notes are visual only, have no ArchiMate element, do not appear in queries, x/y are kept exactly across layout, layout does not move nodes under a note, and notes are not updatable or deletable yet. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with description.

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?

Well-structured with clear sections: intro, usage guidance, Args, Returns, Errors, and limitations. Each sentence adds value, no redundancy. Front-loaded with key purpose and distinction.

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?

Completely covers purpose, usage, all parameters, return values (with output schema noted), error types, and limitations. For a tool with 8 parameters and complexity, the description is thorough and actionable.

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?

Input schema has 0% description coverage, but the description fully explains each parameter: text (non-empty, verbatim, escape sequences not interpreted), x/y (exact integers), width/height (defaults), connect_to_node_ids (accepted ID types), note_id (uniqueness across entire model, namespacing advice). Adds significant value beyond 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 adds a diagram-only note (sticky annotation) to a view. It distinguishes from grouping elements and other tools by specifying that notes are visual only, have no ArchiMate element, and do not participate in model tree or validation.

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 when to use (to comment on a diagram) and when not to use (do not create a Grouping element for comments). Provides reasoning that notes do not pollute the model tree or participate in validation, guiding the agent to choose the right 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?

Annotations indicate readOnlyHint=false and destructiveHint=false, and the description adds context: relationship_id uniqueness across entire model, conditional required parameters, and error types. No contradiction.

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?

Well-structured with Args, Returns, Errors sections; front-loaded with core purpose. Slightly lengthy but every sentence adds value; could be tightened slightly.

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 tool with 11 parameters and no schema descriptions, the description covers preconditions, parameter semantics, error cases, and return shape. Output schema exists, so return values are documented. Complete for agent use.

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 description fully compensates by explaining each parameter with examples, conditional requirements (access_type for Access, influence_strength for Influence), and uniqueness constraint for relationship_id.

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 'Add a new ArchiMate relationship between two elements,' specifying the verb and resource. It distinguishes from sibling tools like add_relationships (bulk) and update_relationship.

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 states that both endpoints must already exist and references list_supported_types for valid values. Does not explicitly state when not to use or mention alternatives, but preconditions are clear.

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

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

The description details rollback_on_error behavior, ID uniqueness across entire model, and includes error types. Annotations (readOnlyHint=false) are consistent with description's write nature.

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 well-structured with sections for notes, item shape, Args, Returns, Errors. It is front-loaded with main action but could be slightly more concise.

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 complexity (batch operation, multiple fields, error types), description covers return structure, error types, parameter details, and behavioral notes. No reliance on output schema needed.

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?

Input schema has 3 parameters: relationships (array), rollback_on_error (boolean), semantic_validation (string). Description provides full item shape with all fields and aliases, and explains rollback default. Schema coverage is 0% but description compensates completely.

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 'Add multiple relationships to the active model in one call' and contrasts with the sibling 'add_relationship' tool, clearly indicating this is a batch version.

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 that each item supports fields from add_relationship and provides notes on ID uniqueness and rollback behavior. It implicitly distinguishes from single-relationship tools but doesn't explicitly state when not to use.

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

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

The description discloses numerous behavioral traits beyond the annotations: advisory nature, scoring algorithm (seven checks, score range, status thresholds), guarantee that 'limited' is the floor, and the error condition (ModelNotFoundError). This adds significant value given the tool has readOnlyHint and openWorldHint annotations that only hint at safety and completeness.

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 clear sections (advisory, scoring, returns, errors) and front-loads the core purpose. It is slightly verbose—especially the return list—but every sentence serves a purpose. A minor trim would improve conciseness without losing clarity.

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 optional parameters and an output schema (implied), the description covers behavior, scoring interpretation, and error conditions comprehensively. However, the lack of input parameter explanations leaves a gap, preventing a perfect score. The output schema is mentioned, so return value details aren't strictly needed, but the description still documents them thoroughly.

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?

With 0% schema description coverage, the description should explain the two parameters (include_hard_validation, include_quality_assurance_views), but it does not. It focuses solely on the output structure. While the schema provides names and defaults, the description adds no meaning about what these boolean flags control or their effects.

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 clearly states the tool returns 'advisory TOGAF-oriented readiness findings' and distinguishes it from validation tools by emphasizing its advisory nature. The verb 'assess' combined with 'readiness findings' makes the purpose specific and distinct from sibling tools like validate_model or build_quality_report.

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 says 'Advisory only' and explains that the compliance_claim is always false, indicating it should be used for review, not formal conformance. It provides scoring context but does not directly mention when to avoid using it or list alternative tools for conformance checking, which would strengthen guidance.

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

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

The description goes beyond annotations by disclosing that engine choice is not stored, that layer bands do not modify the semantic model, and that pyarchimate engine misplaces certain element types and has no collision detection. It also documents error behaviors, adding transparency beyond the idempotentHint and readOnlyHint 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 well-structured with sections, bullet points, and bold parameter names. It front-loads the main purpose and includes detailed options. However, it is somewhat lengthy and has minor redundancy (e.g., band outcomes explained twice), which slightly reduces conciseness.

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, 5 parameters, and an output schema, the description thoroughly covers input semantics, error cases, return values with two detail levels, and engine-specific caveats. It leaves no critical gaps 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?

With 0% schema description coverage, the description fully compensates by explaining every parameter (view_id, strategy, layout_engine, layer_bands, detail) with options, defaults, and behavior details. This adds significant meaning 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 starts with a specific verb and resource: 'Automatically reposition all nodes in a view to avoid overlap.' It then details behaviors for different engines and strategies, clearly distinguishing this layout tool from sibling tools like add_element or export_model_content.

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 indicates when to use this tool (to layout a view) and compares the two layout engines, noting trade-offs. It does not explicitly state when not to use it or list alternatives, but the context is sufficient for an agent to decide.

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?

Annotations provide readOnlyHint=true and openWorldHint=false, and the description aligns with these by presenting a read-only report generation. The description adds behavioral details beyond annotations: it explains the aggregation nature ('aggregate counts throughout'), parameter effects on the report, and the exact structure of the returned data, including optional TOGAF fields and error conditions.

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 separate sections for purpose, usage note, args, returns, and errors. Every sentence adds value, from the opening verb+resource to the detailed return envelope. It is concise but not terse, hitting an optimal length.

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 simplicity (two optional booleans, no required params) and the presence of an output schema (described in detail), the description covers all relevant aspects: purpose, parameters, return structure, error conditions, and usage context. It leaves no gaps for effective agent 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 detailing both parameters. It explains that include_togaf adds data.togaf_readiness with a disclaimer and references assess_togaf_readiness, and that include_quality_assurance_views counts QA-marked views as stakeholder-facing. This adds significant semantic context beyond the parameter names and types.

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

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

The description clearly states it 'builds a structured visual, semantic, coverage, and optional TOGAF report', specifying the verb and resource. It further distinguishes itself from siblings by noting it is 'the tool to poll during a build without paying for full issue lists', making its purpose and niche explicit.

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 advises using this tool during a build for lightweight aggregation ('the tool to poll during a build without paying for full issue lists'). It references assess_togaf_readiness for additional TOGAF scoring, implying an alternative for detailed TOGAF assessment, but does not provide clear exclusion criteria or alternative use cases for other report types.

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

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

The description details behaviors beyond annotations: existing connections are skipped, rollback_on_error mechanism, detail levels affecting response, and error conditions. This adds significant context to the idempotentHint and readOnlyHint 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 well-structured: a one-sentence summary followed by iterative logic, then clear sections for args, returns, and errors. Every sentence adds value without redundancy.

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

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

The description covers the tool's purpose, process, parameters, return values, and errors comprehensively. Given the tool's complexity and available structured data, no gaps remain.

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?

With schema description coverage at 0%, the description fully explains each parameter: view_id (required), detail (enum-like options with effect), and rollback_on_error (default behavior). It adds meaning beyond the schema's type and default values.

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

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

The description starts with a specific verb and resource: 'Add visual connections for every relationship whose endpoints are visible.' It clearly states the tool's function and distinguishes it from sibling tools like 'add_connection_to_view' which operate on single connections.

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 iterative process and when connections are skipped, providing context for use. However, it does not explicitly indicate when not to use this tool or provide comparisons to alternative siblings like 'ensure_all_relationships_in_views'.

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?

Annotations indicate readOnlyHint=true, and the description adds behavioral details: it returns a success envelope with two dicts (elements_by_type and relationships_by_type) and can raise ModelNotFoundError. This goes beyond the annotations, though it does not cover potential rate limits or authorization needs.

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 (two short paragraphs) and front-loaded with the main purpose. Every sentence adds value without redundancy.

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

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

Given the tool has no parameters and an output schema exists, the description sufficiently covers the return structure and error condition. It is complete for the tool's simplicity.

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

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

With zero parameters and 100% schema coverage, the description is not expected to add parameter information. The baseline for 0 params is 4, and the description does not need to compensate.

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 counts active model content grouped by ArchiMate type, specifying both elements and relationships. This distinguishes it from sibling tools like query_elements and query_relationships, which return lists rather than aggregated counts.

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 does not provide explicit guidance on when to use this tool versus alternatives. While the purpose implies it is for summary statistics, it lacks any 'when to use' or 'when not to use' statements, and no alternative tools 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?

Annotations provide destructiveHint but the description goes further: it details the replacement behavior, return envelope structure (`data.model_id`, `data.model_info`), error conditions (`INVALID_MODEL_NAME`), and parameter effects. 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 well-structured: purpose paragraph, then Args/Returns/Errors sections. Front-loaded with the core action. Every sentence adds unique value; no redundant or vague statements.

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 (3 params, destructive, output schema not provided), the description covers all necessary aspects: parameters, return shape, errors, usage context, and relation to sibling tools. No missing information.

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 description must carry full burden. It comprehensively describes all 3 parameters: name (non-empty string), description (optional, comes back as documentation), properties (optional, keys/values coerced to strings). No gaps.

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 what the tool does: 'Create a new empty ArchiMate model and make it the active model.' It distinguishes from sibling tools by explicitly referencing `load_model_*` tools and `update_model`, creating a clear usage boundary.

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 explicitly states when to call: 'before any element/relationship/view tool', and provides alternatives for different tasks. It also notes that `update_model` should be used for later metadata changes.

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?

Annotations indicate destructiveHint=true and readOnlyHint=false; the description adds transactional rollback behavior, field aliases, and error types. It does not mention potential side effects like model overwriting or permission requirements, but provides substantial context beyond 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 lengthy but well-structured with a code block and bullet points. It front-loads the purpose and organizes details logically. While slightly verbose, the complexity of the tool justifies the length.

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 (nested objects, 2 params, 0% schema coverage), the description covers input format, errors, and return summary. An output schema exists but is not detailed in the description; however, the explanation is complete enough for an AI to use effectively.

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% with no descriptions for the two parameters. The description fully compensates by detailing the entire spec object structure, field options, and the rollback parameter's effect. This adds significant meaning absent from 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 'Create a complete ArchiMate model from a structured JSON spec,' using a specific verb-resource pair. It distinguishes itself from sibling tools like 'add_element' and 'create_empty_model' which handle granular operations.

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

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

The description explains the spec format and default transactional behavior, implying use for bulk creation. While it doesn't explicitly state when to use alternatives, the detailed spec suggests a specific use case. Siblings like 'add_elements' exist for simpler batch operations, so the guidance is clear but not exhaustive.

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?

Annotations indicate non-read-only and non-destructive. The description details that invalid viewpoint values are rejected before creation (nothing left behind, view_id reusable), error behaviors, and the uniqueness constraint. This adds significant behavioral context beyond 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 well-structured with Args, Returns, and Errors sections. While detailed, every sentence adds value. It is slightly verbose but appropriately sized for the 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 6 parameters, output schema existence, and annotations, the description is nearly complete. It covers return shape, errors, and usage context with sibling tools. No gaps in required information.

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 thoroughly explains each parameter: `name` (non-empty), `view_id` (optional, UUID, uniqueness across model), `folder_path` (normalization), `viewpoint` (from `list_supported_types`), and mentions `properties` and `description` as optional. It provides critical usage details not in 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 'Create a new ArchiMate view (diagram) in the active model.' It specifies the verb (create), resource (view), and context (active model), and distinguishes from siblings like `add_node_to_view` and `add_connection_to_view`.

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 explicit guidance: use this to create a view, then add nodes/connections with other tools. It advises obtaining viewpoint values from `list_supported_types` and warns about view_id uniqueness across the entire model, including naming conventions for batch commands.

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?

Annotations already declare destructiveHint=true, readOnlyHint=false, openWorldHint=false. The description adds value by detailing that pyArchimate removes dependent concepts, providing behavioral context beyond the 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?

The description is concise with clear sections (Args, Returns, Errors). The first sentence immediately states the purpose, and every sentence adds value without redundancy.

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

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

For a simple one-parameter tool with annotations and an output schema present, the description fully covers the operation: deletion, cascade effects, and error conditions. It is complete and sufficient.

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

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

With 0% schema description coverage, the description provides minimal extra meaning: 'element_id: ID of the element to delete.' This is adequate but does not elaborate on format or other constraints, earning a baseline score of 3.

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

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

The description clearly states it deletes an ArchiMate element from the active model, using a specific verb and resource. It distinguishes itself from sibling tools like delete_relationship and delete_view by focusing on elements.

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 it removes dependent concepts (relationships, visual nodes), indicating it is the comprehensive delete for elements. It does not explicitly state when to use alternatives like delete_relationship, but the context implies appropriate 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?

Annotations already set destructiveHint=true, but the description adds that pyArchimate removes visual connections, which is helpful. It also documents the error case. It does not mention other behavioral details like irreversibility or permission requirements, but overall adds value beyond 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 concise and well-structured: main action, side effect, parameters, returns, errors. Every sentence is relevant and earns its place.

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

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

Given low complexity (1 parameter, output schema present), the description covers input, side effect, output, and error. Minor gap: does not clarify what 'active model' means, but context likely known. Overall 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?

Schema coverage is 0%, but the description includes an Args section explaining the parameter as 'ID of the relationship to delete,' which adds meaning beyond the schema's type-only definition. Could be more detailed about the format or source of IDs.

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

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

The description clearly states it deletes an ArchiMate relationship from the active model, specifying the resource and action. It also mentions the side effect of removing visual connections, distinguishing it from update or other delete operations.

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

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

The description does not explicitly state when to use this tool versus alternatives like update_relationship or delete_element. Usage is implied but not guided with exclusions or comparison to 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?

Annotations indicate destructiveHint=true and readOnlyHint=false. The description adds context by detailing that the view and its visual components are removed while underlying elements/relationships are preserved, which exceeds the annotation information.

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 labeled sections (Args, Returns, Errors). Every sentence adds value, and there is no unnecessary fluff. Could potentially be slightly shorter, but current length is justified.

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

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

The description covers the main behavioral aspects: deletion scope, return value, and error condition. Given the presence of an output schema (implied by 'Success envelope'), the description is complete enough for an agent to understand the tool's effect.

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

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

The schema has 0% description coverage, so the description must compensate. The Args section describes view_id as 'ID of the view to delete', which adds basic meaning but no additional constraints or format details. This is adequate for a single string parameter.

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 'Delete an ArchiMate view from the active model' and specifies what is removed (view and visual nodes/connections) and what is NOT removed (underlying elements and relationships). This distinguishes it from sibling tools like delete_element and delete_relationship.

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 deleting views but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. The context is clear from the tool name and sibling list, but no direct guidance is given.

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?

Annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) provide a high-level safety profile. The description adds critical details: it creates views, modifies model structure (adds nodes/connections), relocates containment connections, and marks views with a property. It also discloses rollback behavior and fixed layout behavior. No contradiction with 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 well-structured: a one-sentence purpose, followed by context, method, and detailed parameter explanations. Every sentence adds substantive value without redundancy or fluff. It earns its length.

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 (5 parameters, no required ones, many siblings), the description covers the algorithm, property marking, error conditions, layout behavior, and return data structure. The output schema is referenced (success envelope with specific fields), providing a complete picture for an agent.

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 contains an 'Args' section that explains each parameter's purpose and constraints (e.g., layout_engine must be 'internal', layout_strategy is validated but not applied, rollback_on_error default true). This fully compensates for the lack of schema documentation.

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

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

The description begins with a specific verb-resource pair: 'Ensure every model relationship is rendered in at least one view.' It explains the context (Archi Validator reports) and details the actions (create/reuse coverage view, add nodes/connections, relocate connections). This clearly distinguishes it from sibling tools like add_node_to_view or auto_layout_view.

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 when to use: when Archi Validator reports 'Unused Relation' or similar. It explains the behavior of coverage views and their detection via property marking. It also lists error conditions. While it does not explicitly mention alternative tools, the context is sufficient for an agent to decide.

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?

Annotations already provide readOnlyHint=true. The description adds value by detailing the CSV format (base columns and custom properties as 'Property:' columns) and the error case 'ModelNotFoundError'. However, it does not disclose potential performance implications or any limits.

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 well-structured. It starts with the primary purpose, then details the output columns, and ends with return format and error. Every sentence is informative with no waste.

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 parameters and an output schema, the description covers the CSV content, return envelope, and a relevant error. It could mention if the export is limited by model size or if there are any side effects, but overall it is sufficiently complete for a simple read 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?

There are no parameters, so schema coverage is trivially 100%. The description does not need to add parameter information, meeting the baseline expectation for no-parameter tools.

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 'Export all active model elements as a CSV string', specifying the verb and resource. It distinguishes from siblings like 'export_model_content' and 'export_relationships_to_csv' by focusing on elements, but does not explicitly differentiate.

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 mentions an error case but provides no guidance on when to use this tool versus alternatives like 'export_model_content' or 'export_relationships_to_csv'. No when-not-to-use or prerequisites are 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?

Annotations indicate the tool is idempotent and non-destructive. The description adds context that auto-layout is per-call only and not persisted, enhancing transparency. However, it stops short of explicitly stating no model modification occurs.

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 Args, Returns, and Errors sections. It could be slightly more concise, but the detail is justified given the number of parameters.

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?

Despite 9 parameters and no schema descriptions, the description fully documents all parameters, return format, and errors. An output schema exists, so the return format detail is sufficient.

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

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

Schema description coverage is 0%, but the description includes a detailed Args section that explains all 9 parameters, including defaults and valid values, fully compensating for the schema 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 clearly states 'Serialize the active model as XML string content,' specifying the verb (serialize), resource (active model), and output (XML string). It distinguishes from the sibling tool `export_model_to_file` by noting when to use each.

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 explicit guidance: 'Use this when the caller wants the XML in the response payload. Use `export_model_to_file` to write directly to disk.' It also explains parameter usage and lists error conditions.

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?

Annotations already indicate idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds important behavioral details: parent directories are created, the layout engine is per-call only, and specific error conditions like suggestions for invalid strategies. No contradiction with 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 well-structured with Args, Returns, and Errors sections. It front-loads the core action. While detailed, it remains readable and avoids redundancy, though some parameter details could be trimmed.

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 has a Returns section (output schema exists) and an Errors section, providing good coverage of outcomes. However, 5 undocumented parameters reduce completeness for a tool of this complexity.

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

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

The schema has 10 parameters with 0% description coverage. The description explains 5 parameters (path, output_format, auto_layout, layout_strategy, layout_engine) and their defaults/conditions. However, 5 parameters (quality_gate, allow_orphans, allow_visual_issues, allow_semantic_issues, include_quality_report) are not mentioned, leaving gaps.

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 'Serialize the active model and write it to a local file,' which is a specific verb+resource pair. It also clarifies the preferred use case for producing a .archimate file that Archi can open directly, distinguishing it from sibling tools like load_model_from_file or export_model_content.

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 states it is 'Preferred when the user wants a .archimate file Archi can open directly,' giving clear context. However, it does not explicitly mention when not to use it or list alternative tools for other scenarios.

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

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

The description adds return format details and error conditions, going beyond the readOnlyHint and openWorldHint annotations. 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 concise and well-structured: purpose, column details, returns, errors. 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 simplicity (no parameters, no input schema complexity), the description covers purpose, output format, and error case completely.

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, so the description adds value by detailing output columns and custom properties. Baseline 4 applies due to 100% schema coverage.

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

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

The description clearly states it exports all active model relationships as a CSV string, with specific columns and custom properties. It distinguishes from sibling export tools like export_elements_to_csv.

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 exporting relationships and notes a prerequisite (active model). It lacks explicit alternatives or when-not-to-use guidance, but the context is clear.

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?

Annotations already indicate readOnlyHint=true, so the description adds minimal behavioral context. It does not disclose what 'valid' means or potential edge cases.

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 concise sentence with no filler, though it could be slightly more informative without losing brevity.

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 complexity of ArchiMate relationships, the description lacks explanation of what constitutes valid options (e.g., metamodel rules) and does not leverage the presence of an output schema.

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

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

Schema coverage is 0%, and the description adds no meaning to the source_type and target_type parameters beyond their 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?

The description clearly states the tool returns valid ArchiMate relationship options for given source and target types, distinguishing it from siblings like recommend_relationship.

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 (to get valid relationship options) but does not provide explicit guidance on alternatives or when not to use.

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?

Annotations already declare readOnlyHint=true, so the description adds context: it prevents source-code inspection and returns a success envelope with specific content (workflows, anti-patterns, etc.). This provides behavioral insight beyond 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 concise with no wasted words. It includes purpose, usage guidance, and return content in a few sentences, making it easy to read and understand.

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 zero parameters and existing annotations, the description fully covers the tool's purpose, when to call it, and what it returns. It is complete for an AI agent to decide to use it.

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

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

The tool has no parameters (schema coverage 100%), so the description correctly doesn't mention parameters. Baseline for 0 parameters is 4, and no additional explanation is 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 a client-facing usage guide for the ArchiMate MCP server. It specifies the verb 'Return' and the resource 'usage guide,' and distinguishes it from siblings by noting it is for server operation guidance.

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 tells when to use the tool: when unsure how to operate the server. It also provides clear alternatives: use prompts, tools/list, and resources/list instead of source-code inspection, preventing misuse.

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?

Beyond the readOnlyHint annotation, the description details what the tool includes (model info, summaries, type counts, etc.) and mentions error conditions (ModelNotFoundError). No contradictions with 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 well-structured with separate paragraphs for purpose, usage, args, returns, and errors. It is concise yet comprehensive, with no redundant information.

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 presence of an output schema and the detailed description covering purpose, parameters, return, and errors, the description is fully complete. It does not rely on the output schema to explain return values.

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

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

Despite 0% schema description coverage, the description fully documents all three parameters with defaults, meanings, and constraints (e.g., sample_limit clamped to 0-50). This compensates completely.

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 inspects the active model without dumping full XML or source code, and lists the types of data it combines. It distinguishes itself from related tools by specifying it is an inspection-only step after loading and before editing.

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 states 'Use this immediately after loading an existing model and before editing.' This provides clear guidance on when to use the tool and implicitly indicates it is not for editing.

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?

Annotations already indicate readOnlyHint=true, so safety is clear. The description adds value by detailing the return structure (three arrays and count fields) and the ModelNotFoundError, which are beyond the 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 concise with three sentences: purpose, usage hint, and returns/errors. Front-loaded with the main action, 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?

With zero parameters and an output schema present, the description sufficiently explains the return fields and error possibilities. It is complete for a simple list 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?

There are zero parameters, so baseline 4 applies per rules (no parameters to describe). The description does not need to add parameter info as the schema is empty and fully covered.

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 specifies 'List elements with no relationships and/or no view placement,' clearly stating the verb and resource. It distinguishes from sibling tools like query_elements by focusing on orphan detection.

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 says 'Useful for finding gaps before completing a model,' which implies usage context but does not explicitly compare to sibling tools or state when not to use. No exclusions or alternatives are provided.

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

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

Annotations already declare readOnlyHint=true, so the tool is known safe. The description adds value by detailing the return structure (success envelope with specific data) and version dependency, which enriches understanding beyond 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 concise at about six sentences, front-loaded with purpose and usage guidance, followed by return structure. Every sentence earns its place; no fluff.

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 (listing many types) and that an output schema exists, the description covers all necessary context: usage scenario, version specificity, return structure details, and the fact that no active model is needed. It is fully 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?

There are no parameters (input schema empty), so the description need not add parameter info. It adequately details return content, which is the main concern. The baseline for zero parameters is 4.

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: 'List supported ArchiMate types and configuration values.' It uses a specific verb+resource construction and distinguishes this tool from siblings, as no other tool lists supported types.

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 tells when to use: 'Always call this before generating model content if you are not certain which names the running pyArchimate build accepts.' It also notes version-specificity and that no active model is required, providing 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?

Disclosures align with destructiveHint: true, stating it 'replaces active model.' Adds safety details (DTD/entity rejection, size limit) beyond annotations. Could mention if undo history is cleared, but overall 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?

Well-structured with Args, Returns, Errors sections. First sentence conveys core purpose. No extraneous text; every sentence adds value. Concise yet comprehensive.

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?

Covers input constraints, output format (success envelope with model_info), errors, and alternative tool guidance. Having an output schema further supports completeness. No gaps identified.

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?

With 0% schema coverage, description fully explains both parameters: model_content constraints (starts with `<`, ≤10 MiB, safety rejections) and content_format enum values and defaults. Adds significant meaning beyond 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?

Clearly states 'Load an ArchiMate model from XML string content (replaces active model)', specifying verb, resource, and source. Distinguishes from sibling 'load_model_from_file' by noting it expects XML payload, not path.

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 advises when to use alternatives: 'For loading large files or paths use load_model_from_file instead; this tool expects the actual XML payload, not a path.' Also includes constraints like size limit and safety rejections.

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?

Annotations declare destructiveHint=true, and description reinforces 'replaces active model'. Additionally, it details file path behavior, format expectations, error types, and response structure.

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?

Well-structured with main description, Args, Returns, Errors sections. Front-loaded with purpose, every sentence adds value, 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 complexity (loading, optional inspection, multiple formats, errors) and presence of output schema, description covers all aspects: inputs, outputs, errors, and distinguishes from 40+ sibling tools.

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?

Input schema has 5 parameters with 0% description coverage, but description fully explains each: path (tilde expansion, relative resolution), content_format (enumeration of formats), inspect_after_load (default true, compact summary), include_semantic_validation (default true), sample_limit (clamped 0-50).

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 uses specific verb 'Load' with resource 'ArchiMate model from a local file' and explicitly states it replaces the active model. It distinguishes from sibling 'load_model_from_content' for raw XML, making 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?

Explicitly states preferred entry point for local .archimate or XML files, advises alternative for raw text, and explains that default inspection avoids extra round trips.

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?

Beyond the readOnlyHint annotation, the description discloses that filters are AND-combined, unknown keys are ignored, possible errors (ModelNotFoundError), and details of the return structure. This adds substantial behavioral context.

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 sections for description, supported filters, arguments, returns, and errors. Every sentence is informative and adds value without redundancy.

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

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

Given the complexity of filters, absence of schema descriptions, and presence of an output schema, the description provides comprehensive guidance on usage, parameters, return values, and error cases. It covers all necessary aspects for correct tool 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 input schema provides only a generic object for filter_criteria with no descriptions. The tool description fully compensates by listing supported keys (type, name_contains, properties_contain) and their semantics, adding meaning 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 it queries elements in the active model with optional filters. It distinguishes from sibling tools like query_relationships, add_element, etc., which operate on different resources or actions.

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 when to use (querying elements with filters or listing all with empty {}) and notes that unknown keys are ignored. It does not explicitly mention alternatives or when not to use, but provides sufficient context for proper invocation.

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?

Annotations already indicate readOnlyHint=true. Description adds query behavior (AND, ignored keys), return object structure, and error types. Provides context beyond 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?

Well-structured with clear sections. Each sentence provides necessary information: filter behavior, supported keys, arguments, returns, errors. No redundant content.

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?

Covers filter behavior, valid keys, return format, errors, and prerequisite (active model). Output schema exists, so return fields are documented. Complete for a query 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 only defines filter_criteria as an object with additionalProperties true. Description enriches by listing valid keys (type, source_id, target_id), their types, and behavior (AND, unknown keys ignored). Fully compensates for 0% schema coverage.

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 clearly states the tool queries relationships in the active model with optional filters. Verb 'Query' and resource 'relationships' are specific. It distinguishes from sibling tools like add_relationship or delete_relationship by focusing on querying.

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?

Describes how filters are AND-combined and how to list all relationships. Mentions error conditions. However, it does not explicitly compare with other query tools like query_elements or advise when to use this over alternatives.

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?

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds no further behavioral details—such as whether the tool checks against a metamodel or what happens with missing parameters. Since annotations cover safety, this is adequate but not insightful.

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

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

A single sentence with no fluff, placing the core action first. However, the extreme brevity sacrifices necessary detail; a sentence or two more would improve clarity without harming conciseness.

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 6 parameters, an output schema, and many sibling tools, the description is too sparse. It fails to explain parameter choices (e.g., id vs type, strict_archimate), leaving the agent under-informed for correct selection and invocation.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only hints that 'source/target ids or types' are used, ignoring 'intent', 'strict_archimate', and the interplay between id and type parameters. This is insufficient for correct invocation.

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 recommends valid relationship types for source/target IDs or types, using a specific verb and resource. It distinguishes from most siblings like 'add_relationship' or 'get_relationship_compatibility', though the latter is closely related and not explicitly differentiated.

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

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

No guidance on when to use this tool versus alternatives like 'get_relationship_compatibility' or 'add_relationship'. The description does not explain the intended context, prerequisites, or exclusions.

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

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

The description adds significant behavior beyond annotations: 'rendering never moves anything', 'SVG is a rendering, NOT a third model format', and 'The markup is written to disk and never returned.' It also explains token size to justify not returning the SVG, and clarifys file creation behavior (expanding ~, creating parent dirs). No contradictions with 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 well-structured with a clear summary first, then usage details, parameter explanations, return value list, and error cases. Every sentence adds value, and there is no redundancy or 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 complexity (file system handling, return data, error conditions, sibling differentiation), the description is fully complete. It covers all necessary context: when to use, what the output is, how parameters work, what returns and errors occur, and how it differs from related tools.

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 fully compensates: 'view_id: ID of the view to render.' and 'path: Output path on the MCP server's filesystem (.svg conventionally). `~` is expanded, relative paths resolve against the server's CWD, and parent directories are created if missing.' This adds crucial meaning 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 'Render one view to an SVG file so a human can look at the diagram,' providing a specific verb and resource. It also distinguishes from siblings like export_model_to_file and auto_layout_view by clarifying that SVG is not a model format and cannot be imported back.

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 on when to use (to check layout, drop into document/chat) and when not to use (not a substitute for export_model_to_file). It also recommends using auto_layout_view first if layout needs work, providing a clear alternative.

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

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

Annotations indicate destructiveHint=true, and the description's verb 'Apply' implies modification without adding detail. The description does not disclose whether operations are reversible, require prior validation, or affect other model aspects, failing to enrich beyond the annotated destructive nature.

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 brief sentence, but it sacrifices necessary detail. While concise, it is not front-loaded with key information (e.g., tool scope, effect), and the jargon reduces efficiency. Every sentence should earn its place; this one does not fully serve the agent.

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 (6 parameters, destructiveHint, output schema), the description is incomplete. It does not explain return values, parameter roles, or prerequisites. The output schema exists but is not referenced, leaving gaps in agent understanding.

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% with six parameters, but the description mentions none. Parameters like 'repair_ids', 'auto_layout', and 'rollback_on_error' are undefined, forcing the agent to rely solely on parameter names which may be ambiguous.

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 'Apply selected deterministic semantic relationship repairs,' which identifies a specific action and resource. However, the term 'deterministic semantic relationship repairs' is jargon and not explained, reducing clarity compared to more self-explanatory sibling tools like 'validate_semantics'.

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 offers no guidance on when to use this tool versus alternatives. With many sibling tools for editing, validation, and reporting, the lack of explicit when-to-use/when-not-to-use advice leaves the agent to infer usage 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?

The description adds significant behavioral context beyond the annotations (readOnlyHint=true) by detailing the return structure (success envelope with data containing model name, counts) and potential errors (ModelNotFoundError). No contradictions with 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 concise yet comprehensive: three paragraphs covering purpose, usage, return values, and errors. Every sentence adds value, and it is well-structured for quick reading.

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 parameters and the presence of an output schema (mentioned in description), the description fully covers all necessary details for an agent to understand the tool's behavior, return structure, and error conditions.

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?

With no parameters and 100% schema coverage, the baseline is 4. The description effectively explains what the tool does without needing parameter details, fulfilling the need for completeness.

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 summarizes the active model with counts, view summaries, and totals. It distinctly differentiates from sibling tools like 'summarize_view' by focusing on the entire model.

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 specifies that the tool is useful for verifying generation results without dumping full XML, providing a clear context. However, it does not explicitly mention when not to use it or suggest alternatives among the many sibling tools.

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

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

Annotations already declare readOnlyHint=true, so safety is clear. The description adds valuable behavioral context: return fields (including relationships not yet drawn) and specific error conditions (ModelNotFoundError, ViewNotFoundError). 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 concise with a clear structure: a one-line summary followed by Args, Returns, Errors sections. Every sentence adds value, no fluff.

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 only one parameter, is read-only, and has an output schema, the description fully covers what the agent needs: what it does, what it returns, and possible errors. No gaps remain.

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?

With 0% schema description coverage, the description compensates by documenting the single parameter 'view_id: ID of the view to summarize.' This adds meaning beyond the schema's type 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 uses a specific verb ('Summarize') and resource ('a single view'), and lists exactly what it returns: node count, connection count, gaps. This clearly distinguishes it from sibling tools that modify or create views.

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?

While the purpose is clear, there is no explicit guidance on when to use this tool versus alternatives. It is implied that this is for getting summary statistics before or after modifications, but no exclusions or scenarios are provided.

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

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

Discloses key behaviors beyond annotations: updates are partial (only specified fields change), properties merge with existing (use empty to clear), folder path must match category, and element type immutability. No contradiction with 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?

Well-structured with Args, Returns, Errors sections. Each sentence adds value; no fluff. Length appropriate for 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?

Covers all important aspects: partial update semantics, property merging rules, folder path constraint, type immutability, return type, and specific error cases. Output schema exists but description still summarizes return value.

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 has 0% description coverage, so description fully compensates. Explains updates dict structure, lists supported keys with types and constraints, and describes element_id usage. Adds meaning beyond 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?

Clearly states 'Update an existing ArchiMate element' with specific verb and resource. Differentiates from sibling tools like add_element and delete_element by explicitly noting element type cannot be changed, leaving recreation as alternative.

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 guidance on partial updates via updates dict and property merging. Mentions when to recreate instead of update for type changes. However, lacks explicit comparison to sibling update tools like update_model.

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?

Adds significant behavioral detail beyond annotations: updates are merged, properties are merged, unknown keys cause specific errors, idempotent behavior implied by merge semantics. Error cases are listed. No contradiction with 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?

Well-structured with Args, Returns, Errors sections and front-loaded purpose. Minor verbosity in error details could be streamlined, but every sentence adds value. Efficient for the 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 tool has one complex parameter and no output schema details shown, the description provides complete context: active model constraint, error types with details, return shape reference. No gaps 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?

Input schema has 0% description coverage (just 'additionalProperties: true'), but the description's Args section fully defines supported keys, types, constraints (non-blank, stripped), aliases, and merge behavior. Compensates completely for schema lack.

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?

Clearly states 'Update the active model' with specific fields (name, documentation, properties). Distinguishes from sibling update_element by noting different behavior on unknown keys and clarifies it works on any loaded model, not just locally created ones.

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 contrasts with update_element ('unknown keys are rejected rather than ignored'), guides when to use each. Also explains the updates dict semantics (only change specified fields, merge properties) and the active model constraint, giving clear context for invocation.

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

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

The description reveals that updates merge 'properties' and that certain fields ('access_type', 'influence_strength') are only meaningful for specific relationship types. Annotations indicate idempotent (idempotentHint=true) and non-destructive, which aligns with the update semantics.

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

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

The description is well-structured with sections for Args, Returns, Errors, and a note about immutability. It is slightly verbose but every sentence adds value; bullet points improve 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 (2 parameters with nested object), the description covers return type (Success envelope with RelationshipDetail), error cases, and parameter details. With an output schema present, it is sufficiently 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?

Despite 0% schema description coverage, the description thoroughly explains both parameters: 'relationship_id' as the ID, and 'updates' as a mapping with supported keys and their types/restrictions (e.g., 'name' as string, 'access_type' constrained to specific values). This fully compensates 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 'Update an existing ArchiMate relationship' and specifies immutable fields (endpoints, type) versus mutable ones. This distinguishes it from sibling tools like 'add_relationship' and 'delete_relationship'.

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 endpoints and type cannot be changed and advises recreating to change those. While it does not explicitly say 'when to use this tool,' the context of updating versus adding or deleting is clear.

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?

Annotations indicate idempotentHint=true. Description adds that viewpoint validation prevents partial updates, specifying that unknown viewpoint leaves view untouched. Provides error handling details.

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?

Efficiently structured with a clear purpose statement, constraints, then Args/Returns/Errors sections. Every sentence adds value; 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?

Combined with annotations and output schema, the description fully covers tool purpose, constraints, parameters, return, and errors, enabling correct agent 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 coverage is 0%, but description thoroughly documents all parameters: view_id, updates (with supported keys and merge behavior for properties), and viewpoint (validation, default null).

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?

Clearly states 'Update an existing ArchiMate view' and explicitly distinguishes itself from sibling tools like add_node_to_view and add_connection_to_view by noting that nodes and connections are managed elsewhere.

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 when-to-use (metadata updates) and when-not-to-use (nodes/connections), names specific alternatives, and explains viewpoint validation 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?

Discloses delegation to pyArchimate helpers, exclusion of certain connectors, and error conditions (ModelNotFoundError). Annotations already mark it read-only; the description adds meaningful behavioral context beyond that.

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?

Structured into clear sections: purpose, delegation details, return data, errors. Every sentence is essential, no filler. 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 no parameters and a rich output schema, the description covers purpose, usage guidelines, behavioral details, return structure, and errors. It is fully sufficient for an agent to decide when and how to use this 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?

No parameters exist, so the description cannot add parameter semantics. Baseline is 4 for zero-parameter tools. The description compensates by detailing return fields, which adds value beyond 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 validates visual references in the active model, specifying it checks invalid connections and nodes. It distinguishes itself from the sibling 'validate_semantics' by clarifying one is for visual references and the other for semantic checks.

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 when to use (for visual references) and when not to (use validate_semantics for semantic checks). Also clarifies that diagram-only annotation connectors are excluded from defect reporting, giving clear guidance on what is and isn't checked.

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?

Annotations declare readOnlyHint=true, and the description adds detailed behavioral traits: specific checks performed, parameter effects, return structure, and error types. 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 well-organized with clear sections (purpose, checks, args, returns, errors). Every sentence adds value, and it is front-loaded with the 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?

Despite having only one parameter and an existing output schema, the description fully covers the tool's behavior, return values, and errors. It is complete for its complexity and sibling 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?

The single parameter detail is thoroughly explained with examples of output size and guidance on choosing summary vs full. This compensates for the 0% schema description coverage.

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

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

The description clearly states it runs ArchiMate semantic checks beyond visual reference validation, and lists specific check categories. This distinguishes it from sibling tools like validate_model and repair_semantic_issues.

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 guidance on when to use the detail parameter (summary vs full) and mentions error conditions, but does not explicitly compare to sibling tools or state when not to use this tool.

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