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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a mutation operation (aligning elements likely changes their positions), but does not specify whether this is destructive, requires permissions, has side effects, or what the output looks like. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

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

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

The description is a single, concise sentence that directly states the tool's function. It is front-loaded with the core action and avoids unnecessary words, making it efficient and easy to parse.

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

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

Given the tool's complexity (mutating element positions), lack of annotations, no output schema, and low schema description coverage, the description is incomplete. It does not address key aspects like what happens after alignment, error conditions, or how it interacts with sibling tools, leaving the agent with insufficient information for reliable 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?

The input schema has 0% description coverage, so the description must compensate. It mentions 'specific position' but does not explain the parameters: alignment (with enum values like left, center) or elementIds (an array of IDs). The description adds minimal meaning beyond the schema, failing to clarify what alignment means in context or how elementIds are used.

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

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

The description states the tool's purpose as aligning elements to a specific position, which is clear but vague. It specifies the action (align) and target (elements), but does not distinguish it from sibling tools like distribute_elements or group_elements, nor does it clarify what type of elements (e.g., UI components, graphics) or context (e.g., layout, design) it operates on.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as needing existing elements to align, or differentiate from similar tools like distribute_elements or group_elements. Without any context, the agent must infer usage based on the tool name alone.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. 'Create' implies a write operation, but it doesn't specify permissions needed, whether the element is saved immediately, if there are rate limits, or what happens on failure. This is inadequate for a mutation tool with zero annotation coverage.

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

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

The description is a single, efficient sentence that gets straight to the point without any wasted words. It's appropriately sized for the tool's basic purpose, though this conciseness comes at the cost of completeness.

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 creation tool with 13 parameters, 0% schema coverage, no annotations, and no output schema, the description is severely inadequate. It doesn't explain what an 'Excalidraw element' is, how parameters interact, what values are returned, or 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?

The description provides no information about any of the 13 parameters, despite 0% schema description coverage. Parameters like 'type' with an enum or 'roughness' are completely unexplained, leaving the agent to guess their meaning and usage.

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

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

The description clearly states the verb ('Create') and resource ('a new Excalidraw element'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'update_element' which might also create elements through updates, leaving room for ambiguity.

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 no guidance on when to use this tool versus alternatives like 'update_element' or 'query_elements'. There's no mention of prerequisites, context, or exclusions, leaving the agent to infer usage from the tool name alone.

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

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

No annotations are provided, so the description carries full burden. 'Delete' implies a destructive mutation, but it doesn't disclose if deletion is permanent, requires specific permissions, affects related elements, or what happens on success/failure. This leaves significant behavioral gaps for a destructive operation.

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

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

The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.

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 destructive tool with no annotations, 0% schema coverage, and no output schema, the description is inadequate. It lacks details on behavior, parameters, outcomes, and usage context, leaving the agent with insufficient information to invoke it safely and correctly.

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

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

Schema description coverage is 0%, with one parameter 'id' undocumented in both schema and description. The description adds no meaning beyond the tool name, failing to explain what 'id' represents (e.g., element identifier, format, source) or how to obtain it, which is critical for a deletion tool.

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 ('Delete') and resource ('an Excalidraw element'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'update_element' or 'create_element' in terms of when deletion is appropriate versus modification or creation.

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 is provided on when to use this tool versus alternatives. With siblings like 'update_element' and 'create_element', there's no indication of whether deletion is irreversible, when it's preferred over updating, or any prerequisites for 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Distribute elements evenly' implies a layout operation but doesn't specify whether it modifies elements (e.g., repositioning), requires specific permissions, has side effects, or what the expected outcome is. This is inadequate for a tool with potential mutation effects.

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 extremely concise with 'Distribute elements evenly'—a single, front-loaded phrase that directly states the action. There's no wasted verbiage, making it efficient in terms of word count, though this brevity contributes to its lack of detail.

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

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

Given the complexity of a layout tool with 2 parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects, parameter details, or usage context, leaving significant gaps for the agent to infer functionality. This is insufficient for effective tool 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 compensate for undocumented parameters. It mentions 'elements' and 'evenly', which loosely relates to 'elementIds' and 'direction', but doesn't explain what 'elementIds' represent (e.g., IDs of graphical objects) or how 'direction' affects distribution. The description adds minimal 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 'Distribute elements evenly' states a general action but lacks specificity about what 'elements' are or what 'distribute' means in this context. It's vague compared to sibling tools like 'align_elements' or 'group_elements', which have clearer scopes. The description doesn't distinguish this tool from potential alternatives, making it minimally informative.

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 no guidance on when to use this tool versus alternatives like 'align_elements' or 'group_elements'. There's no mention of prerequisites, typical scenarios, or exclusions. This leaves the agent without context for selecting this tool appropriately among the siblings.

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

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

No annotations are provided, so the description carries full burden. It only states 'Get an Excalidraw resource', which implies a read operation but doesn't disclose behavioral traits such as permissions needed, rate limits, whether it's idempotent, or what the output looks like. This is a significant gap for a tool with no annotation coverage.

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

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

The description is a single sentence, 'Get an Excalidraw resource', which is very concise and front-loaded. It wastes no words, but it may be overly terse given the lack of detail needed for clarity and completeness.

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 (1 parameter with enum but no output schema or annotations), the description is incomplete. It doesn't explain what 'Get' does operationally, what the resource types entail, or what the return value is. For a tool with no structured support, this leaves too many gaps for effective 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?

The input schema has 1 parameter with an enum list (scene, library, theme, elements) but 0% schema description coverage. The description doesn't add any parameter details beyond the schema, but since there's only one parameter and the enum provides clear options, the baseline is high. However, it doesn't explain what each enum value means, so it doesn't fully compensate for the coverage gap.

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

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

The description states the tool 'Get an Excalidraw resource' which provides a basic verb ('Get') and resource type ('Excalidraw resource'), but it's vague about what specific resources are available or what 'Get' entails (e.g., fetch metadata, retrieve content). It doesn't distinguish from siblings like 'query_elements' or 'create_element', leaving ambiguity in scope.

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 is provided on when to use this tool versus alternatives. With siblings like 'query_elements' and 'create_element', there's no indication if this is for general resource retrieval, specific types, or different contexts. The description lacks any when-to-use or exclusion statements.

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

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

No annotations are provided, so the description carries full burden for behavioral disclosure. It states 'Group multiple elements together' but doesn't explain what grouping entails (e.g., creates a parent-child relationship, affects visibility/editing), whether it's destructive to existing structures, permission requirements, or error conditions. This leaves critical behavioral traits unspecified.

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, efficient sentence with zero wasted words, making it highly concise. It's front-loaded with the core action and target, though its brevity contributes to gaps in other dimensions.

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 (mutating operation with no annotations, 0% schema coverage, and no output schema), the description is incomplete. It lacks details on behavior, parameter usage, output expectations, and how it interacts with sibling tools like 'ungroup_elements', failing to provide sufficient context for effective 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 description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'multiple elements' which loosely relates to the 'elementIds' array parameter, but doesn't clarify what constitutes valid element IDs, format expectations, or minimum/maximum array size. This adds minimal semantic value beyond the schema's basic structure.

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 ('Group') and target ('multiple elements together'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from its sibling 'ungroup_elements' beyond the opposite action, missing explicit differentiation about when grouping versus ungrouping applies.

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 no guidance on when to use this tool versus alternatives like 'align_elements' or 'distribute_elements', nor does it mention prerequisites (e.g., elements must exist). It implicitly suggests grouping multiple elements, but lacks explicit context or exclusions for usage.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool prevents modification, implying a mutation with side effects, but lacks details on permissions required, whether locking is reversible (though 'unlock_elements' exists as a sibling), error conditions (e.g., invalid IDs), or system-wide impacts. This is inadequate for a mutation tool with zero annotation coverage.

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

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

The description is extremely concise at 5 words, front-loading the core action ('Lock elements') and purpose ('to prevent modification') without any wasted text. Every word earns its place, making it easy to parse quickly.

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 as a mutation operation with no annotations, no output schema, and 1 undocumented parameter, the description is incomplete. It lacks essential context such as return values, error handling, permissions, or how locking interacts with other tools (e.g., if locked elements can still be queried). The presence of 'unlock_elements' as a sibling hints at reversibility but isn't explicitly stated.

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 1 parameter with 0% description coverage, and the tool description provides no information about parameters. It doesn't explain what 'elementIds' represents (e.g., format, source, or constraints), leaving the agent to guess based on the schema alone. With low schema coverage, the description fails 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 verb ('lock') and resource ('elements') with a specific purpose ('to prevent modification'). It distinguishes from siblings like 'unlock_elements' by indicating the opposite action. However, it doesn't explicitly differentiate from other modification-related tools like 'update_element' or 'delete_element' beyond the general prevention concept.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing existing elements), exclusions (e.g., cannot lock already locked elements), or direct comparisons to siblings like 'unlock_elements' for reversing the action or 'update_element' for when modification is needed instead.

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

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

No annotations are provided, so the description carries the full burden. It mentions 'optional filters' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires specific permissions, how results are returned (e.g., pagination), or any rate limits. This leaves significant gaps for a query tool.

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

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

The description is a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, clearly stating the tool's core function without unnecessary details.

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

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

Given no annotations, 0% schema coverage, no output schema, and 2 parameters (one with an enum but unexplained), the description is incomplete. It doesn't cover key aspects like return values, error handling, or how to interpret the 'filter' object, making it inadequate for effective 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 description coverage is 0%, so the description must compensate. It hints at 'optional filters' but doesn't explain what 'filter' or 'type' parameters mean, their formats, or how they interact. With 2 parameters and no schema descriptions, this adds minimal value 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 'Query Excalidraw elements with optional filters' states the verb (query) and resource (Excalidraw elements), which is clear. However, it doesn't distinguish this tool from siblings like 'get_resource' or 'update_element'—it's vague about what makes 'query' different from 'get' or how it relates to other element 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?

No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_resource' (which might retrieve elements) and 'create_element'/'update_element' for modifications, the description offers no context for choosing 'query_elements' over them or any 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Ungroup' implies a mutation operation, but the description doesn't state whether this requires specific permissions, whether it's reversible, what happens to element properties after ungrouping, or error conditions. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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

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

The description is a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it immediately scannable. Every word earns its place by conveying essential information 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's mutation nature, lack of annotations, no output schema, and 0% schema coverage, the description is incomplete. It doesn't address behavioral aspects like side effects, permissions, or return values, nor does it clarify parameter semantics. For a tool that modifies grouped elements, more context is needed for safe and effective 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 description coverage is 0%, so the description must compensate for the undocumented parameter. It mentions 'groupId' implicitly through context but provides no details on what a group ID is, how to obtain it, format requirements, or validation rules. The description adds minimal value beyond what the parameter name suggests.

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 ('ungroup') and resource ('a group of elements'), making the purpose immediately understandable. It distinguishes from siblings like 'group_elements' by specifying the opposite operation. However, it doesn't specify what 'elements' refers to in this context (e.g., UI elements, graphic objects), which prevents a perfect score.

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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., that elements must already be grouped), when not to use it, or what happens after ungrouping. With siblings like 'group_elements' and 'lock_elements', explicit usage context would be helpful but is absent.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('unlock') and outcome ('allow modification'), but doesn't describe permissions required, whether unlocking is reversible, side effects (e.g., if other users can now modify elements), rate limits, or error conditions. For a mutation tool with zero annotation coverage, this is a significant gap in transparency.

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

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

The description is extremely concise ('Unlock elements to allow modification')—a single, front-loaded sentence with zero wasted words. It efficiently communicates the core purpose without unnecessary elaboration, making it easy to parse quickly.

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 1 parameter with 0% schema coverage, no annotations, no output schema, and siblings indicating it's part of a mutation workflow (e.g., with 'lock_elements', 'update_element'), the description is incomplete. It doesn't cover parameter details, behavioral traits like permissions or side effects, or usage context relative to siblings, making it inadequate for safe and effective use by an AI 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?

The input schema has 1 parameter ('elementIds') with 0% description coverage, and the tool description provides no information about parameters. It doesn't explain what 'elementIds' are (e.g., identifiers of UI elements, database records), their format, or constraints (e.g., must be locked elements). With low schema coverage, the description fails to compensate, leaving parameters undocumented.

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 'Unlock elements to allow modification' clearly states the verb ('unlock') and resource ('elements'), and specifies the purpose ('to allow modification'). It distinguishes from siblings like 'lock_elements' (opposite action) and 'update_element' (requires unlocked state). However, it doesn't explicitly differentiate from all siblings like 'align_elements' or 'group_elements' in terms of when unlocking is necessary versus other 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., elements must be locked first), when not to use it (e.g., if elements are already unlocked), or alternatives (e.g., using 'update_element' directly if elements are unlocked). Given the sibling tools include 'lock_elements', some context could have been added about the workflow.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool updates elements but doesn't describe what happens during the update (e.g., partial vs. full updates, error handling, permissions required, or rate limits). For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.

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, clear sentence with no wasted words. It's front-loaded with the core purpose and efficiently conveys the essential action and target. Every word earns its place, making it highly concise and well-structured.

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 (14 parameters, mutation tool), lack of annotations, and no output schema, the description is incomplete. It doesn't address behavioral aspects like error conditions, return values, or usage context. While concise, it fails to provide sufficient context for effective tool selection and invocation in this environment.

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

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

The description provides no information about parameters beyond what's implied by the tool name. With 14 parameters, 0% schema description coverage, and no output schema, the description fails to add any semantic context (e.g., explaining 'id' is required, what 'type' enum values mean, or how 'opacity' scales). This is inadequate given the high parameter count and low 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 the action ('Update') and resource ('an existing Excalidraw element'), making the purpose immediately understandable. It distinguishes itself from siblings like 'create_element' and 'delete_element' by specifying it's for existing elements, though it doesn't explicitly contrast with similar tools like 'query_elements' or 'lock_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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an element ID), exclusions (e.g., not for new elements), or comparisons to siblings like 'create_element' for new elements or 'query_elements' for retrieval. Usage is implied but not explicitly stated.

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