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

With no annotations, the description fully discloses behavior: each call is a separate save causing live updates, elements clip at panel edges, and it describes return values, concurrency conflicts (HTTP 409), and the detailed behavior of bindings and field paths. This exceeds what annotations would typically 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?

Although long, the description is well-structured with clear sections (element kinds, bindings, field paths, concurrency, layout, hardware). It is front-loaded with the core purpose and return values, and every section serves to inform correct usage of add_element. The length is justified by the complexity of the element object and its many options.

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 output schema, no annotations, and low schema coverage, the description covers all necessary aspects: element schemas, return values, concurrency, editing strategies, layout guidance, and hardware constraints. It also cross-references sibling tools (list_widgets, probe_widget_data, arrange, etc.) to provide complete context for using add_element 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?

The input schema has 0% description coverage, but the description compensates by thoroughly explaining the 'element' object, including all kinds, fields, binding transforms, and field paths. It also explains the 'base_rev' parameter in the context of avoiding clobbering concurrent edits. This adds immense semantic 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 clearly states the tool appends ONE element to a canvas, saves, and returns specific values. It also differentiates from set_canvas for replacing the whole layout, making the primary purpose distinct and unambiguous.

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

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

The description explicitly explains when to use this tool vs alternatives: 'Use set_canvas to replace the whole layout at once' and 'update_element / delete_element / patch_canvas change one thing without re-sending the whole document... add_element appends one.' It also provides concurrency guidance with base_rev and mentions related tools like arrange and measure_text for layout intent.

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

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

With no annotations, the description carries the burden. It discloses the output format, the role of gap/pad/cols, and notes the results are baked in as editable normal elements. It does not detail error behaviors, but for a pure computation tool the description is transparent enough.

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 bit long but front-loaded with the core purpose and packed with useful details. Every sentence adds value; minor verbosity around 'bake them in' and 'spread them across' is acceptable.

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, no annotations, and no output schema, the description covers the essential behavior, return shape, and key parameter semantics. It does not address edge cases like insufficient space, but for the tool's scope it is reasonably complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains gap, pad, and cols (including default), and mentions layout types. The description adds meaning beyond the bare parameter names, though it does not detail the layout parameter's variants beyond naming them.

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 computes aligned child boxes within a bounding box for grid/row/column layouts, with a specific verb ('Compute') and resource ('count aligned child boxes'). It distinguishes from siblings like add_element or update_element by focusing on layout computation rather than direct manipulation.

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

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

It explains the tool is for placing cells 'by intent instead of hand-computing pixels', giving clear context. It does not explicitly name alternatives or when not to use, but the context is sufficient and does not mislead.

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

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

With no annotations, the description must carry transparency. It does disclose that the page is 'new' and 'empty' and that the tool returns an id, but it doesn't mention side effects, prerequisites, or whether h/w dimensions can be adjusted later. Some behavioral context is given, but not exhaustive.

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 two sentences that front-load the core purpose and then give actionable next steps. Every phrase adds value, and there is no redundant repetition of schema 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?

For a simple creation tool, the description covers the essential context: what is created, the returned id, the immediate next step (set_canvas), and how to size the canvas (using list_devices). It stops short of explaining parameter default behavior or required name, but the schema covers those basics.

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

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

Schema coverage is 0%, so the description must compensate for parameter meaning. It explains that h and w are for sizing to the target panel and points to list_devices, but it does not specify units or fully describe the name parameter. Name is self-evident from the schema, but the description adds limited detail beyond the parameter 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 action: 'Create a new, empty canvas dashboard and return its id.' It specifies the resource ('canvas dashboard') and distinguishes it from sibling tools like set_canvas, which is for layout, and list_pages, which is for viewing existing pages.

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 clear usage context: use this tool to create the empty page first, then follow up with set_canvas() for layout, and size the page using list_devices. It doesn't explicitly state when not to use this tool or alternative creation methods, but the workflow guidance is strong.

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

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

With no annotations, the description must disclose behavioral traits. 'Remove' implies destructiveness but does not explicitly state irreversibility, permission requirements, or what happens if the element does not exist. It only mentions the return value briefly, leaving notable 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 sentence, concise and front-loaded with the main action. It wastes no words and effectively communicates the core operation and return 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 tool's simplicity and lack of annotations, the description is minimally adequate: it states the action and return value. However, it omits important context such as the role of page_id, the meaning of base_rev, error behavior, and whether deletion is permanent, making it incomplete for full operational clarity.

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 clarifies that element_id is the ID of the element to remove, but page_id and base_rev remain unexplained. The phrase 'by id' only partially covers the parameter semantics, leaving most parameters under-specified.

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

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

The description uses the specific verb 'Remove' with the resource 'element from a canvas by id,' clearly differentiating it from sibling tools like update_element or add_element. It also specifies the operation is for exactly one element, which prevents confusion with bulk 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 implies when to use it (when you need to delete a single element by ID) but does not provide explicit exclusions or alternatives, such as when to use update_element or patch_canvas instead. There is no mention of prerequisites like existing page or element.

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

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

With no annotations, the description carries the full burden. It discloses the return payload (canvas plus rev/updated_at/updated_by) and a key concurrency behavior (409 if the page drifted). It does not explicitly state read-only or permissions, but 'Get' and the absence of side effects imply safety.

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

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

The description is two sentences: the first front-loads the main purpose, and the second adds actionable workflow guidance about rev. No wasted words, and every sentence 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?

For a simple read tool with no output schema, the description adequately explains returned fields and the recommended base_rev flow. It is self-contained enough for an agent to select and invoke correctly, though it omits explicit error handling for the GET call itself.

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 only parameter, page_id, has no schema description (0% coverage). The description implies page_id identifies the page via 'for a page', but adds no constraints, format, or examples. This is minimal compensation for the 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 states a specific verb ('Get') and resource ('full canvas document') scoped to a page, enumerating contents ('size, appearance, and every element') plus metadata fields. This clearly distinguishes it from write/update siblings like set_canvas, patch_canvas, and add_element.

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

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

The description advises keeping the returned 'rev' and passing it as 'base_rev' on the next write to detect drift via HTTP 409, establishing a clear read-before-write workflow. It does not explicitly name alternatives or say when not to use the tool, but the context is strong.

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

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

With no annotations, the description carries the burden of disclosing behavior. It explains that the tool pages through results, supports case-insensitive substring filtering via q, and intentionally avoids including all choices in get_widget_options to prevent schema bloat. This adds meaningful behavioral context beyond what the schema implies, though it does not detail return structure or 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 two sentences: the first states purpose and rationale, the second elaborates on the q parameter. It is concise, front-loaded, and every sentence adds value with no filler.

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

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

For a paginated list tool with no annotations, no output schema, and 5 parameters, the description covers the key points: paging behavior, filtering option, and why it exists. It does not describe return format or limit/offset boundaries, but these are minor for a read-only paging endpoint, making the description reasonably complete.

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

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

Schema coverage is 0%, so the description must compensate. It explicitly defines 'q' as a case-insensitive substring filter on value/label and implies limit/offset through 'Page through.' However, the required parameters 'widget' and 'option' are only referenced generically as 'one of a widget's options' and are not elaborated on, leaving potential ambiguity about their formats or allowed 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 clearly states the tool's function: 'Page through the choice rows for one of a widget's options.' It uses a specific verb ('page through') and resource ('choice rows'), and explicitly distinguishes it from sibling get_widget_options by explaining why choices are kept separate. This makes the purpose immediately clear.

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

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

The description provides context for when to use this tool: it's for paging through many choice rows to avoid bloating the schema, and it mentions the q filter for substring matching. However, it does not explicitly state 'use get_widget_options when you need all choices at once' or provide other exclusionary guidance, so it falls just short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose a key behavioral trait: big choice lists are omitted by default and can be inlined or paged via get_widget_choices. This is useful. However, it doesn't disclose the full return structure, any potential errors, or permissions required. For a read-only getter, this is adequate but not exceptional.

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 front-loaded with the core action. Three sentences cover purpose, format hints, and choice list handling without redundancy. Every sentence earns its place, and the structure is easy to scan.

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

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

For a simple read-only tool with no output schema, the description provides sufficient context: what it does, how to use it, key behavioral notes about choice lists, and explicit alternatives. The only minor gap is the widget identifier format, but this is compensated by the description's overall clarity and the presence of sibling tools like list_widgets.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain include_choices well ('pass include_choices=True to inline them') and notes the default behavior. However, it does not clarify the format or identifier for the widget parameter, leaving the most important parameter underspecified. An agent would still need to infer widget ID format from siblings or examples.

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 ('Get the configurable options') and the resource ('for one widget'). It also explains the purpose (fill an element's options correctly) and distinguishes itself from the sibling get_widget_choices by mentioning alternatives for paging through choice lists, making it specific and unambiguous.

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

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

The description provides clear context for when to use the tool: to retrieve configurable options for a single widget. It also explicitly names an alternative (get_widget_choices) for paging through large choice lists, and explains the include_choices parameter for inlining. However, it doesn't explicitly exclude usage relative to other siblings like list_widgets or probe_widget_data, so it falls short of a full 5.

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

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

With no annotations, the description carries the burden. It transparently describes the output fields and the practical consequence of ignoring the palette, but it does not disclose any operational behaviors such as whether the list is cached, ordered, or reflects live hardware state. For a zero-parameter read-only list, this is adequate but not rich.

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

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

The description is compact and front-loaded: a one-line purpose, a field list, and a single actionable sentence. No filler or redundancy; every sentence 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?

For a no-param, no-output-schema tool, the description covers the key return fields (color_mode, colors, gamut, orientation, mono) and connects them to a concrete workflow. It loses a point because 'panel dims' is mentioned but the exact width/height field names are not explicitly listed, leaving minor ambiguity.

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

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

The tool has zero parameters, so the schema already exhaustively covers them (100%). The description still adds value by explaining how the returned data should be used (match canvas w/h, avoid quantization), which earns the baseline 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 opens with a specific verb and resource—'List registered display devices'—and immediately scopes the result to panel dimensions and color capabilities. It distinguishes itself from sibling list tools (list_widgets, list_pages) by naming display-device-specific fields.

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 provides clear context for when to use: to obtain a target panel's width/height and design within its color palette so colors don't quantize. It does not explicitly name alternatives or exclusions, so not a 5, but the usage intent is well implied.

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

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

With no annotations provided, the description must disclose behavioral traits itself. It merely restates the listing function without mentioning read-only nature, return format, ordering, or any side effects. No additional behavioral context is given beyond the verb 'List'.

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, tightly worded sentence that immediately conveys the tool's purpose with no filler or 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 is minimal and, given the absence of an output schema and annotations, does not explain what the returned list contains (e.g., IDs, names, metadata). For a zero-parameter list tool, this lack of return-format detail makes it incomplete, though the basic purpose is clear.

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 zero parameters, so there is nothing for the description to add. The 0-parameter baseline of 4 applies, and the description neither contradicts nor needs to explain parameters.

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 ('List') and the resource ('existing canvas (freeform) dashboards'), making it distinct from sibling tools like list_widgets and list_devices. The parenthetical clarifies the type of dashboard, which adds precision.

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 such as get_canvas or set_canvas. It only states what the tool does, leaving the agent to infer its 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?

There are no annotations, so the description carries the full burden. It discloses that the tool lists widgets and appearance options, which implies a read-only operation, but it does not explicitly state side-effect-free behavior, output format, or any limitations (e.g., whether it only returns widgets for the current canvas). Some behavioral context is added beyond the name, but not a rich disclosure.

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 packs in the core purpose (list widgets), scope (canvas), and additional details (fragments, theme/style/font options). There is no redundant wording or filler, making it highly efficient.

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

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

For a simple listing tool with no parameters and no output schema, the description is reasonably complete: it states what is listed and what extra information is included. Minor gaps exist around whether it returns all widgets globally or per canvas, and there is no explicit mention of output structure, but these are not critical given 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?

The tool has zero parameters and the schema is empty with 100% coverage. The baseline for zero-parameter tools is 4. The description clarifies what is being listed, which compensates for any need to explain parameter meaning, though no parameter-specific semantics are required.

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 ('List') and specifies the resource ('every widget that can be placed on a canvas'), including additional scope ('with its fragments' and 'available theme/style/font appearance options'). This clearly distinguishes it from sibling tools like list_pages or list_devices, and from get_widget_options which targets a specific widget.

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: use this tool when you need to enumerate all widgets available for a canvas and their appearance options. However, it does not explicitly mention when not to use it or compare it to alternatives like get_widget_options, get_widget_choices, or probe_widget_data. The context is clear but exclusions are 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?

With no annotations, the description carries the full burden and does well: it explains the return payload structure, the meaning of 'fits', and the dependency on widget font names from list_widgets. It implicitly indicates read-only behavior through 'Measure', but does not explicitly rule out side effects or describe error handling.

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

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

The description is exactly two sentences, front-loaded with the primary action and purpose, and packs input shape, output shape, and a prerequisite into a compact, well-organized format. No filler or redundant phrasing.

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 simple parameter setup and lack of output schema, the description covers purpose, input structure, output structure, and a key dependency. It omits edge cases like missing fonts or invalid max_width, but remains complete relative to the tool's 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 input schema is minimal (array of objects with additionalProperties true), so the description compensates by fully specifying the items structure: {text, font?, size?, weight?, max_width?}. It also clarifies the output and the meaning of 'fits', which is more than the schema provides. Minor ambiguity remains about exact units or value formats.

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 measures rendered text dimensions to fit a box, with a specific verb ('Measure') and resource ('text in a widget font'). It distinguishes itself from sibling tools by focusing on measurement rather than rendering or modification.

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 sizing containers to avoid clipping and mentions the dependency on list_widgets for font names, providing clear context. However, it does not explicitly call out alternatives or when not to use the tool, so it stops short of full exclusionary 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?

With no annotations, the description carries the transparency burden. It discloses that the operation is a partial update ('without touching the elements') and that it returns an acknowledgment ('Returns the ack'). However, it does not mention permissions, side effects, or behavior on invalid input, leaving some 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 two sentences, front-loaded with the action and scope, and every sentence adds value (what, what-not, alternatives, return value). No redundancy or 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 no annotations, no output schema, and only a 0%-coverage schema, the description is adequate for a simple patch operation but leaves gaps: 'patch' structure, 'base_rev' semantics, and any error handling are undocumented. It provides the essential context but not full completeness.

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 lists allowed field names but does not explicitly map them to the 'patch' object parameter, nor does it explain the purpose of 'base_rev' or the structure of 'patch'. The description adds some semantic insight but fails to fully clarify parameter 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 tool's function: 'Change document-level fields' and explicitly lists the target fields (name, w, h, theme, style, font, bg, bg_image, bg_fit). It also distinguishes from sibling tools by noting it does so 'without touching the elements' and referencing update_element/set_canvas for element-level changes.

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

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

Explicit guidance is given: use this tool for document-level fields, and use update_element/set_canvas for elements. This directly addresses when to use this tool vs alternatives, though the mention of set_canvas for elements is slightly ambiguous given the sibling name.

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 excels by documenting the return structure, explaining the meaning of each data_source value ('live', 'sample', 'error'), and noting that fields list only bindable dot-paths with sample values and that an empty payload has null fields. This goes well beyond basic transparency and prevents common misuse.

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, dense paragraph, but it is well-organized with a colon introducing the return shape and subsequent clauses explaining edge cases. Information density is high, and there is no filler, though breaking it into multiple sentences would improve readability. It earns a 4 because it is efficient and purposeful.

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 absence of an output schema and annotations, the description thoughtfully explains the return value and behavioral nuances (live/sample/error, field paths, null handling). It covers most of what an agent needs to safely invoke the tool. The missing 'options' parameter explanation is a notable gap, preventing a score of 5.

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

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

The input schema has 0% description coverage, so the description must compensate for parameter semantics. The 'widget' parameter is only implied as the target entity, and the 'options' parameter is completely undiscussed—its meaning, allowed values, and impact on the result are left unknown. The description focuses entirely on the output, leaving users to guess how to properly specify the 'options' object.

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

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

The description opens with 'Return a widget's data as JSON to pick field paths before binding a data primitive,' which clearly states the action, resource, and purpose. It is specific enough to distinguish this from siblings like list_widgets (which just lists widgets) or get_widget_options (which fetches configuration), making the tool's unique role clear.

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

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

The description explicitly frames the tool's usage: 'to pick field paths before binding a data primitive.' It also warns that the 'data_source' field distinguishes live data from sample/error, so users won't mistake placeholders for real results. While it doesn't explicitly name alternative tools or say 'don't use for X', the context is clear and actionable.

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

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

With no annotations, the description carries the full burden of disclosing side effects. It states the push is explicit, but does not mention permissions, reversibility, potential device-side effects, or return/error behavior. This is similar to the update_drive case where the side-effectful nature is clear but other behavioral traits are unstated.

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

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

Two sentences, front-loaded with the primary action and then the key constraint. Every word contributes either to what the tool does or how to invoke it. No filler or 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 two-parameter tool with no output schema, the description covers the core action and the key parameter source. However, it leaves page_id semantics implicit and does not mention successful/failed outcomes or side effects, so it is minimally viable but not 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?

Schema description coverage is 0%, so the description must compensate. It adds meaning to device_ids by specifying the source (list_devices) and that it is required, but page_id is not explained beyond the schema's 'Page Id' title. Partial compensation only.

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 phrase 'Render the canvas and push it to the given devices' and clearly identifies the resource (canvas) and target (devices). It also references the source of device IDs ('ids from list_devices'), distinguishing this push action from preview/report siblings.

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

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

The description gives clear contextual guidance: device_ids come from list_devices and are required, with 'pushing is always explicit' reinforcing when invocation is appropriate. It does not explicitly name alternative tools for when-not-to-use, but the guidance is sufficient for selecting this tool correctly.

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

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

No annotations are provided, so the description carries the full burden. It discloses the output (PNG at authored size) and frames the tool as a visual checkpoint within an iterative process, implying it is non-destructive. However, it does not explicitly state that no changes are made to the canvas or clarify any potential limitations (e.g., resolution constraints), which would further enhance transparency. The strong feedback-loop context earns above-average credit.

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 tight and efficient: three sentences that immediately state the primary operation, then add workflow context and an alternative. Every clause earns its place, with no filler or 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 single-parameter rendering tool without an output schema, the description is remarkably complete. It explains the output format (PNG), the purpose (visual layout check), how to integrate it into an iteration cycle, and when to prefer a sibling tool. No critical context is missing.

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

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

With schema description coverage at 0%, the description must compensate. It does not mention page_id at all, leaving its meaning and format entirely to the schema's 'Page Id' title. While the parameter's name is intuitive, the description adds no semantic value or usage hints, making this a gap given the low 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 tool's function: 'Render the canvas to a PNG at its authored size and return the image.' It specifies the resource (canvas), the action (render to PNG), and distinguishes from the sibling render_report by contrasting the visual image output with machine-readable 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?

It provides explicit guidance on when to use this tool—as part of an iterative feedback loop ('place → render_preview → adjust → set_canvas → render_preview again')—and explicitly names an alternative for different needs: 'use render_report()' for machine-readable checks. This exceeds simple descriptions and directly addresses tool selection.

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

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

With no annotations, the description carries full burden and excels: it discloses the detailed JSON structure (resolved box, text, overflow/clip flags, data_source, computed colours, board background/theme) and highlights an edge case (widget cells render into shadow DOM so their text may be empty). This is rich behavioral context beyond a basic 'returns a report'.

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

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

The description is appropriately sized for the information density; it opens with the core purpose, then uses a semicolon-separated list for output fields and a parenthetical caveat. While slightly long, every sentence contributes valuable detail and there is 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?

For a tool with one parameter and no output schema, the description is quite complete: it covers what is returned, the use case, and a notable edge case. It omits explicit mention of page_id semantics and potential failure modes, but the overall context is strong and self-contained.

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 one required parameter, page_id, with no description attribute (schema_description_coverage = 0%). The tool description never mentions page_id or explains how to find/format the page identifier, leaving the parameter's meaning implicit. Since coverage is low, the description should compensate but does not.

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 ('Read back') and clearly identifies the resource (what a canvas actually rendered, as JSON). It distinguishes itself from render_preview by explicitly being a companion that returns structured data instead of an image, and enumerates the returned fields.

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 context for when to use it: 'Use it to verify a render — catch clipping, confirm live data, read the real colours — without parsing a PNG.' It references the companion render_preview but does not explicitly name alternative tools or specify when not to use it, missing the 'exclusions' bar for a 5.

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

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

Despite lacking annotations, the description discloses the compact ack return format, HTTP 422 and 409 error behaviors, concurrency handling with base_rev, and clipping behavior for elements. It also states that unresolvable bindings are skipped, which is a subtle runtime behavior an agent must know.

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 long but extremely well-structured with headings for element kinds, live bindings, field paths, and best practices. Every section adds necessary detail for correct invocation; there is no filler. It is front-loaded with the core purpose and then dives into specifics in a logical order.

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 (nine element kinds, bindings, field paths), the description covers return values, error handling, alternatives, and related tools (probe_widget_data, render_preview, arrange, measure_text). It even advises checking hardware palette via list_devices. An agent has everything needed to invoke correctly without external documentation.

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 more than compensates. It explains base_rev usage in detail ('Pass it as base_rev to a write'), provides an exhaustive schema for the canvas object (w/h/theme/style/font/bg/els), and page_id is self-explanatory from context. This far exceeds what the bare schema offers.

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

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

The description opens with 'Replace a canvas dashboard's document', a specific verb+resource statement that clearly defines the tool's purpose. It further distinguishes from siblings by recommending update_element/patch_canvas for one-field changes, making the unique role of set_canvas 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?

Provides explicit usage guidance: 'For a one-field change prefer update_element / patch_canvas' and sections like 'EDITING WITHOUT RESENDING EVERYTHING' and 'AVOID CLOBBERING A CONCURRENT EDIT' explain when to use this tool vs alternatives. It also advises calling render_preview() after setting, and mentions layout/systematic tools as supporting context.

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

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

With no annotations, the description carries the full burden. It discloses key semantics: the merge behavior ('patch is a partial element... merged over the existing one') and the special 'options'/'parts' wholesale replacement, plus the return ('Returns the ack'). This is beyond what the schema provides, though it doesn't mention error conditions or concurrency.

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

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

The description is front-loaded with the primary purpose, then explains the core parameter semantics, then gives a usage example and return value. Every sentence earns its place, and there is no fluff. It is dense yet 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?

For a small update tool, the description covers the essential behavior, use case, and return. However, it omits explanation of the base_rev parameter and doesn't clarify potential error or conflict behavior. Given the simple parameter set and lack of output schema, this is adequate but not exhaustive.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'patch' well, including the partial merge and the special replacement of 'options'/'parts', but does not describe page_id or base_rev at all. This is a notable gap for a required and an optional 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 opens with 'Change ONE element in place without re-sending the whole document,' which uses a specific verb (change), a clear resource (element), and a scope qualifier (ONE, in place). This clearly distinguishes it from related tools like add_element or patch_canvas, which target the whole canvas.

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 provides clear context: 'The cheap edit path for a big canvas: change a precision, a colour, a location, one box.' This tells the agent when to use it, but it does not explicitly name alternatives or state when not to use it (e.g., versus patch_canvas). The guidance is implied rather than explicit.

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