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 discloses the refusal of duplicate visual names, limits collateral changes to missing renderer resources and registration, and enumerates what is left untouched (native visuals, slicers, bookmarks, filters, themes, model objects). It also warns about the Desktop external-change reload prompt. It does not cover failure/rollback behavior if the write partially fails.

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?

Four dense sentences, front-loaded with the action and followed by constraints and side effects in a logical order. The '@vilsem/core' package reference adds little for an agent but costs only a few words.

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

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

For a mutating tool with no annotations and no output schema, the side-effect and safety disclosure is strong, but the description leaves the most complex inputs (spec, bindings with its 1-6 measure limit, layout) entirely unexplained. An agent knows what the tool will and won't change but not how to construct the payload.

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% across 7 parameters including nested spec, bindings, and layout structures. The description only obliquely hints at pageName and visualName ('one existing PBIR page', 'existing visual names are refused') and says nothing about spec, bindings, layout, reportDir, or the optional connectionId. This leaves the agent dependent on bare schema property names for the hardest inputs.

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

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

States a specific verb and resource ('Add one Vilsem Renderer visual to one existing PBIR page using @vilsem/core') with explicit cardinality and target scope. This clearly separates it from siblings like update_visual, preview_visual, and validate_visuals.

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

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

The description implies usage context by constraining to one existing page and refusing existing visual names, which tells the agent this is a create-only path. However it never names alternatives such as preview_visual or validate_visuals, and does not say whether validation should precede the commit.

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 declares read-only behavior, that no model objects are created or changed, and that schemaOnly connections cannot execute queries or live previews. Gaps remain around the lifecycle of a connection (whether it persists, how it is closed) and error behavior when no model is open or the reportDir cannot be resolved.

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 lead sentence is well front-loaded and the mode guidance is compact, but the byPath/byConnection clause is dense jargon (definition.pbir, TMDL, SSAS) that does not correspond to any schema field and reads as internal documentation leaking into the tool description.

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 nested oneOf parameter with no annotations or output schema, the description covers modes, read-only semantics, the connectionId handoff and the schemaOnly limitation. It could go further on what a successful connection returns and on failure modes, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it mostly does: it explains what the report, desktop and fabric variants each need (reportDir, port, workspaceId/datasetId). However it references 'byPath' and 'byConnection' modes that do not appear anywhere in the input schema, which leaves a dangling concept the agent cannot map to a 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 first sentence gives a specific verb, resource and scope: 'Connect read-only to an existing model'. It also implicitly positions the tool as the prerequisite for the schema/DAX/preview siblings, so an agent can tell what it is for without opening the schema.

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 states an explicit preference order ('Prefer source.kind="report" with reportDir') and then explains when each alternative applies: desktop auto-detects a port, fabric takes workspaceId/datasetId. It also states the downstream usage rule ('Keep connectionId for schema, DAX and previews') and a hard constraint for schemaOnly connections.

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 disclose the safety-relevant facts: it is read-only and writes no files. It also lists the return artifacts (patch diff, PNGs, critique). However, it omits what happens if the visual doesn't exist, that live rendering costs time/side effects, and any permission requirements.

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

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

Three short sentences, front-loaded with purpose and output artifacts, then the safety and usage cues. 'This writes no files' mildly repeats 'Read-only' but serves as deliberate emphasis rather than padding.

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

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

The description covers outputs and the non-destructive behavior well, which matters since there is no output schema. But for a five-parameter tool with a nested spec object, zero schema description coverage and no annotations, the total absence of parameter guidance leaves the definition materially incomplete.

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% across five parameters (reportDir, pageName, visualName, spec, connectionId), and the description explains none of them. Notably the required 'spec' object and optional 'connectionId' are entirely opaque to the caller, so the description does not 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 a specific verb and resource ('Read-only comparison against one saved vilsem visual') and names concrete outputs (JSON Patch diff, before/after live PNGs with critique). It doesn't explicitly name a sibling tool, but the phrasing clearly separates it from validate_/preview_/update_ tools by emphasizing comparison against an already-saved visual.

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?

'Run before replacing an existing design' gives a clear usage context that implicitly routes the agent away from update_visual/commit_visual until a diff has been inspected. It stops short of naming alternatives or stating when not to use it (e.g., when the visual does not yet exist).

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 alone; it does establish non-mutating intent via 'Explain' and the explicit non-modification clause. However, it never says whether the 'exact DAX query' is actually executed against the model (and thus has cost/latency/side effects), what happens when the spec is invalid, or what authorization the connection requires.

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

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

Two tight sentences with the primary output content front-loaded and the scope caveat second; nothing reads as filler. Density is high but each element (spec, bindings, ECharts option, DAX query) 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?

There is no output schema, and the description partly compensates by listing what the explanation contains. But for a tool with nested objects, a UUID connection reference, and a row cap, it omits the meaning of two parameters and says nothing about failure modes or response structure.

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 four parameters, two nested, so the description must compensate and largely does not. It covers only 'spec' and 'bindings' at a name level; 'connectionId' (which model the DAX targets) and 'maxRows' (a sampling bound up to 10000) are never mentioned, leaving half the input surface unexplained anywhere.

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 ('Explain') and enumerates exactly what gets explained: the spec, field bindings, resolved empty-data ECharts option, and exact DAX query. The closing negative clause ('Does not inspect or modify native visuals or model objects') carves out scope against read_visual/update_visual, though it never names the sibling that should be used for those cases.

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?

'before preview or commit' gives concrete ordering guidance that ties this tool to specific siblings in the workflow. The exclusion of native visuals and model objects provides when-not guidance, but no alternative tool is named for those scenarios.

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

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

With no annotations supplied, the description carries the whole load and does well on several axes: read-only framing ('without writes'), a 60s profiling cache with an explicit invalidation path, and 'unavailable fields carry explicit errors' signalling graceful degradation. It still omits permission requirements, response envelope, and how large a payload 'full' produces, which matters for a verbose model dump.

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

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

Front-loaded with the read-only framing and tightly packed, but sentences run together into a near-run-on with typographic slips ('up to10 distinct samples', 'cached60s'). Information density is high and little is wasted, though bullet-style separation of the detail/refresh/page rules would improve scanability.

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 5-parameter tool with no annotations, no output schema and zero schema description coverage, the description supplies most of what an agent needs: return content, cache behaviour, default behaviour and the page/reportDir coupling. The residual gaps are connectionId semantics and the shape of the returned object.

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

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

Schema coverage is 0%, so the description must compensate and largely does: it defines the summary/full trade-off, the refresh/cache relationship, and explains that page requires an internal or display page name plus reportDir or a report-kind connection, adding meaning well beyond the bare schema types. connectionId is the one required parameter left unexplained, likely a deliberate assumption.

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

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

Opens with a specific verb and resource: 'Read model context without writes', then enumerates what the read returns (DAX cardinality, BLANK share, min/max, distinct samples, hidden/key flags). The agent can tell this is a model-introspection tool, though it never names a sibling (list_pages, run_dax, connect_model) to sharpen the boundary.

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

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

Gives explicit conditional guidance for two parameters: 'Default detail=summary omits measure DAX and relationship graph; ask for full to understand calculations and join paths' and 'use refresh after model/data changes.' No when-not guidance or comparisons to sibling tools, so the agent must infer the division of labour with list_pages/run_dax on its own.

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 and does state that the tool is read-only and does not edit or validate native visuals, slicers, bookmarks, filters or themes. It also sketches the returned content (page and visual names, types, positions), though it omits behavior on invalid paths or empty reports.

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 capability and followed by tightly scoped exclusions; no filler. The second sentence's list of out-of-scope artifacts is dense but earns its place as scope fencing.

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

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

For a one-parameter read tool with no output schema, the description covers purpose and scope but leaves the sole input unexplained and gives no notion of output shape or error conditions. Adequate but with clear gaps given zero schema description coverage.

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

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

There is one required parameter, reportDir, with 0% schema description coverage, and the description never mentions it or explains the expected directory structure. The only parameter's semantics are left entirely to inference from its name.

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 concrete verb and resource ('Read existing PBIR pages and visual names, types and positions') and adds a stated purpose. The exclusion sentence implicitly separates it from validate_visuals/commit_visual, though no sibling is named directly.

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?

'so you can choose a page and avoid overlap' gives a clear usage context (inspect before placing new visuals). The second sentence supplies when-not-to-use guidance by ruling out editing and validation tasks, but no alternative tool is named explicitly.

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 must carry behavioral disclosure. 'List' implies read-only access, but the description does not explicitly state side effects, permissions, return format, or pagination behavior. It does add useful context that these are shared templates with contracts and a prerequisite doc to read before modifying them.

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

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

Two sentences with no waste. The core purpose is front-loaded, followed by a concise usage prerequisite.

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 zero-parameter list tool with no output schema, the description covers what is listed and a key usage prerequisite. Minor gaps remain because it does not describe the return shape or explicitly state read-only behavior, but overall it is sufficient.

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

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

The tool takes zero parameters, so parameter semantics are not a burden. The description appropriately does not invent parameter details, and the empty schema is fully consistent.

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 a specific verb and resource: list shared Vilsem declarative visual templates with slot and parameter contracts. It distinguishes the resource from siblings like list_pages and get_schema implicitly, but does not explicitly name an alternative tool.

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

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

It gives clear usage context: use these templates as starting points and read vilsem://docs/spec-format before changing token expressions or formatter templates. It does not state when not to use the tool or name an alternative sibling.

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 meaningful behavior: native visuals are skipped, thumbnails are live by default (implying a heavier call), and no manifest file is required. It does not state read-only safety, authorization needs, cost of live thumbnail rendering, or failure behavior for missing/invalid reportDir.

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

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

Three tight sentences, front-loaded with what is returned, then the default behavior and the opt-out flag. The closing sentence 'No separate manifest is used' is cryptic and adds little without context on what would otherwise be needed.

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 three-parameter read tool with no annotations and no output schema, the description covers the main payload and the thumbnail mode well. It falls short on connectionId, on the reportDir path expectations, and on any indication of how results are structured or bounded across multiple pages.

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 'thumbnails' well, and 'reportDir' is loosely implied by 'from PBIR', but 'connectionId' is never mentioned and its role (live thumbnail source?) is left entirely 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?

States a specific verb ('Read') and resource ('vilsem Renderer visual across report pages from PBIR') and enumerates the returned payload (summary, bindings, version, layout, thumbnail). The exclusion of native visuals further scopes it. It does not explicitly distinguish itself from siblings like read_visual or list_pages, and the term 'vilsem Renderer' is unexplained jargon.

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

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

Gives a clear usage rule for the thumbnails flag (defaults to live, pass false for metadata-only discovery), which is genuinely helpful for a discovery tool. However, there is no guidance on when to choose this over read_visual, explain_visual, or list_pages, so the agent must infer sibling 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 the full burden. It usefully discloses that all candidates are rendered from ONE identical bound-data query and that bindings/measures must be shared so numbers cannot drift, which is real behavioral value. However it does not say what happens when the shared-binding constraint is violated (hard error vs. advisory), nor anything about cost, permissions, or how many queries are actually executed.

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

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

Three dense sentences, front-loaded with the core action and output, with the invariant rationale attached to the rule it explains. Minor formatting defects ('Compare1..4', 'labelled2x2') mar an otherwise tight structure.

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 does cover the return value, which matters since no output schema exists, and it explains the core invariant. But for a 10-parameter tool with nested binding objects and zero schema descriptions, essential call-shaping details (labels alignment, reportDir purpose, row limits) are missing, leaving an agent to guess.

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

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

Schema description coverage is 0% across 10 parameters, so the description must compensate and largely does not. It references specs, labels and bindings conceptually but gives no meaning for connectionId, theme, width/height, locale, maxRows, or reportDir, and does not explain the labels-to-specs correspondence that the 2x2 layout depends on.

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

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

States a specific verb and resource ('Compare 1..4 candidate specs'), the shared-data mechanism, and the return artifact (labelled 2x2 PNG plus per-candidate critique). It implies the distinction from single-visual preview tools via the 1..4 candidate framing, but never names preview_visual or diff_visual, so the sibling separation is inferred rather than stated.

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?

'Use this to choose between approaches before committing' gives a clear decision-point context for invocation. It lacks explicit exclusions (e.g. use preview_visual for a single spec, validate_spec to check correctness) and says nothing about prerequisites such as requiring a live connection.

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 load and does so well: it declares critique defaults to true, explains the theme resolution precedence chain (report theme when reportDir supplied, explicit spec.canvasTheme overrides, stored pane override wins), and warns that bounded queries do not prove population coverage. Gaps remain around render cost/latency and permissions, but the mutability and defaulting behaviour are unusually well disclosed.

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

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

Front-loaded with the core action and output, and no sentence is filler — each one adds either a default, a precedence rule, or a caveat. Some sentences pack multiple clauses (theme resolution) and read as terse internal shorthand, costing a bit of scannability.

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 10-parameter tool with nested objects, no annotations and no output schema, the description covers the render/critique outcome and the tricky defaulting behaviour, but leaves the shape of the returned PNG payload and the era/critique result unexplained, and says nothing about bindings semantics. Adequate to call it, not quite enough to call it confidently the first time.

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

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

Schema coverage is 0%, so the description must compensate and it partly does: theme, reportDir, critique and maxRows (1..10000, default 200) all get meaning and precedence rules beyond the bare schema. However width, height, locale, connectionId and especially the nested bindings.measures/dimensions structure are left entirely to the schema, and "bindings" is the most complex parameter present.

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

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

States specific verbs and outputs: validate a spec, query bound fields, return a PNG plus critique, and explicitly negates a neighbouring capability ("This does not write a report"). It is distinguishable from commit_visual/validate_spec by the rendering-plus-critique output, though it never names a sibling, and the phrase "plus option and actionable critique" is awkward enough to blur what exactly is returned.

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

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

Gives real workflow direction: "inspect its limitations and iterate before committing," which tells the agent to loop on previews before persisting. It also signals the tool is non-writing. It stops short of routing to alternatives such as preview_variants or validate_spec, so the agent must infer which preview/validation tool to pick.

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 supplied, the description carries the full burden and does fairly well: 'Read' signals a non-destructive operation, and it discloses the exact return payload including the current live PNG, which is behavior an agent cannot get from the schema. It omits failure modes (missing visual, bad connectionId, missing definition.pbir) and any cost/time expectations, keeping it short of a 5.

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

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

Two tight sentences with the payload enumeration front-loaded and the connection rule second. The long comma-separated list of return fields is dense jargon but each item is informative rather than filler; no sentence is wasted.

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

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

Because there is no output schema, the description's enumeration of returned artifacts is the main compensating strength. Against that, three required identifiers are undocumented in both schema and description, and no error behavior is described, so completeness is adequate but has clear gaps.

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

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

Schema description coverage is 0% across four parameters, so the description must compensate and largely does not. Only connectionId receives added meaning (an alternative to resolving the model through definition.pbir); reportDir, pageName, and visualName are never explained, so an agent must guess how they compose to identify a visual.

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?

Uses a specific verb (Read) plus a named resource (saved vilsem visual) and enumerates exactly what the read yields: migrated spec, provenance, bindings, layout, scoped measures, format-pane overrides, and PNG. It also carves out a scope boundary ('Never reads native visuals'), which separates it from preview_visual/explain_visual implicitly, though those siblings are not named.

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 states the connection requirement ('Uses connectionId or connects through definition.pbir') and one hard exclusion (native visuals), which is real usage guidance. However, it never says when an agent should choose this over explain_visual, preview_visual, or diff_visual, so the routing decision is left to inference.

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

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

With no annotations supplied, the description carries the full burden and does disclose the key traits: the operation is read-only, cannot make persistent model changes, does not expose XMLA, and caps output at maxRows (default 200). It omits secondary behavior an agent might want, such as error handling for malformed DAX, timeouts, or how a connectionId is obtained/kept alive.

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 action and resource, then the return-size constraint, then usage and scope exclusions. No filler and nothing repeated verbatim from the schema beyond a useful default restatement.

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 three-parameter, read-only query tool with no output schema, the description covers what is executed, what comes back (bounded rows), and what it will not do. The remaining gap is the connectionId lifecycle and result shape (columns vs. rows), which an agent would have to infer from sibling tools.

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

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

Schema description coverage is 0%, so the description must compensate. It does constrain 'dax' to an EVALUATE table query (a real semantic requirement beyond the schema's string type) and restates the maxRows default, but it says nothing about 'connectionId' — its uuid format, whether it comes from connect_model, or what happens if it is stale.

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

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

The description names a specific verb and resource ('Execute a read-only DAX EVALUATE table query against a connected model') and scopes it to table queries only. It implicitly separates itself from schema/model-management siblings (get_schema, connect_model) by framing this as data inspection, but it never names an alternative sibling explicitly.

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

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

'Use it to inspect data and verify visual bindings' gives a concrete use context, and the closing clause rules out two adjacent use cases (XMLA commands, persistent model changes). It stops short of naming which sibling to use instead when the agent actually wants schema or connection setup.

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 so well: it discloses validation/preview behavior, the returned diff and before/after PNGs, the dryRun:true default, preservation of manual format-pane objects unless resetFormatting is set, refusal of renderer identity/prototype/version paths, etag-based optimistic concurrency, and that native/model/report objects are never edited.

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?

Dense and front-loaded, leading with the core operation and following with safety-relevant constraints. Every sentence adds information, though the run-on semicolon chaining makes it slightly harder to scan than a cleanly bulleted set of constraints.

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 mutation tool with no annotations and no output schema, the description covers the critical behavioral surface: safety defaults, protected paths, concurrency, and return values. The remaining gap is the four unexplained path/identity parameters, which an agent must infer from naming alone.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate. It meaningfully explains patch (RFC6902), dryRun, resetFormatting, and etag, but leaves reportDir, pageName, visualName, and connectionId entirely undocumented in both schema and description.

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

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

States a specific verb and resource ('Apply RFC6902 JSON Patch to the stored vilsem spec') and implicitly separates itself from siblings like diff_visual, preview_visual, and commit_visual by describing patch-application with built-in preview. An agent can identify the operation without opening the schema.

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

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

Usage is implied rather than stated: the dryRun default and 'validates and previews before writing' tell the agent this is the safe path to mutate a spec, and the etag note hints at a review-then-commit flow. However, it never explicitly says when to prefer this over commit_visual or diff_visual, nor when to set dryRun:false.

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 disclose that validation runs against 'the connected engine' and covers references, cycles, and scalar DAX. It does not say whether the call is non-mutating, nor what happens on failure (thrown error vs. returned diagnostics), and there is no output schema to cover that. Adequate but leaves real 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?

Two sentences, front-loaded with the core action, then the prerequisite and sequencing. No filler. The 'Resolve a Vilsem spec without data' opener carries domain jargon but is dense with information rather than redundant.

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 taking a nested, free-form spec object with zero schema coverage, no annotations, and no output schema, the description covers when and how to invoke it but not what a valid spec looks like or what the result contains. An agent knows when to call it, but not how to interpret the outcome.

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

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

Schema description coverage is 0%, and the spec parameter is an unconstrained object with additionalProperties {}, so the schema conveys nothing about its structure. The description compensates for connectionId by stating its conditional requirement, but says nothing about the shape of spec or what 'measures' contains. The most complex parameter remains entirely opaque.

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 and resource (resolve/validate a Vilsem spec) and qualifies it with 'without data', which separates it from the rendering path. It also enumerates what is checked: schema references, cycles, and scalar DAX. It stops short of distinguishing itself from the sibling validate_visuals, leaving some ambiguity about 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?

Explicit lifecycle guidance is given: 'Run before preview_visual', which tells the agent where this fits in the workflow. The conditional prerequisite 'With spec.measures, connectionId is required' is also actionable. However, it never states when to use validate_visuals instead, nor what to do if validation fails.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses what the result contains (schema errors, unreadable spec literals, unsupported current-renderer specs) and what is silently skipped, but says nothing about permissions, whether it is purely read-only, or whether it fails fast versus collecting all errors.

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

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

Three tight sentences with the scope constraint front-loaded and the exclusions last. No filler, though the GUID phrasing is more opaque than it needs to be for a reader without domain context.

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?

No output schema and no annotations, so the description must explain returns — which it partly does by enumerating the reported error categories. The gap is the sole input parameter and any indication of result shape or granularity (per-visual vs aggregate), which leaves it short of complete for a validation tool.

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

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

Schema description coverage is 0% and the single parameter reportDir has no description in the schema. The description never mentions reportDir, its expected layout, or whether it points at a report root or a PBIR subfolder, so the agent gets no help on the one input it must supply.

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 gives a specific verb (validate) and a narrowly scoped resource (PBIR visual containers whose visualType is the stable Vilsem Renderer GUID), which lets an agent distinguish this from a general validation tool. The term 'Vilsem Renderer GUID' is domain jargon not resolvable from the definition itself, so the boundary is clear in shape but not fully in content.

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

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

It states a negative scope ('Native visuals and all report-level objects are neither validated nor reported'), which is genuine when-not guidance. However, it never names the alternative for those excluded cases (e.g. validate_spec, which exists as a sibling), leaving the agent to infer the routing.

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