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

Beyond the annotations (which are all false), the description discloses that the report's publicCustomVisuals are modified and that Power BI Desktop downloads the visual from AppSource when opening the report. This adds useful behavioral context, though it does not mention permissions or network 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?

The description is two sentences: the first states the core action and target, the second covers the default behavior and download-side effect. Every sentence earns its place 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?

The tool has no required parameters and an output schema, so basic invocation is covered, but the missing parameter semantics and lack of alternative-tool guidance leave gaps. It is adequate for the simple no-argument use case but not fully complete for selecting other AppSource visuals.

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 carries the full burden but only explains the no-argument case. It does not explain what visual_id values are expected or the purpose of request_id, leaving the agent guessing about both 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 opens with 'Registra un custom visual de AppSource en el informe (publicCustomVisuals)', a specific verb plus the resource (AppSource custom visual) and target (report). It also clarifies the no-argument default to 'HTML Content', distinguishing it from generic visual creation tools like pbi_create_visual or pbi_add_image_resource.

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 by stating that without arguments it registers 'HTML Content', which tells the agent when no visual_id is needed. However, it does not explicitly state when to use this tool over siblings such as pbi_create_visual or pbi_create_html_visual, nor does it mention any exclusions.

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

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

Annotations already indicate a non-read-only action, and the description adds valuable behavioral details: the file is copied to StaticResources, report.json is modified, and a missing declaration causes a blank visual with no error. It also explains the return value. This goes beyond the structured metadata and enhances transparency.

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

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

The description is concise and well-structured: it front-loads the purpose, explains the mechanism and failure mode, then describes the return value and the only parameter it documents. Every sentence contributes essential information with no redundancy.

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

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

The description covers the core purpose, the critical mechanism, the failure mode, and the return value, making it usable for the primary workflow. However, given that schema coverage is 0%, the lack of explanation for `name`, `overwrite`, and `request_id` is a notable gap. The tool is simple enough to be used despite this, but completeness is only average.

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

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

The input schema has no parameter descriptions (0% coverage), so the description must compensate. It only explicitly documents `path` (with allowed extensions .png .jpg .gif .bmp .svg). It indirectly mentions the return `item_name`, which may relate to `name`, but `name`, `overwrite`, and `request_id` remain unexplained, leaving ambiguity for the agent.

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

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

The description clearly states the tool's purpose: 'Incrusta una imagen en el informe' (embeds an image in the report). It specifies the exact mechanism (copy to StaticResources, declare in report.json) and the return value (item_name), making it distinct from sibling tools like pbi_add_custom_visual. This is a specific verb+resource+outcome, not a tautology.

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: when you need to embed an image resource into a Power BI report. It also warns about the silent failure if both steps are not performed, which is helpful. However, it does not explicitly mention alternatives or when-not-to-use, but the purpose is narrow enough that this is not a major gap.

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

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

The description discloses rich behavioral details beyond annotations: Power Query step naming, real-file-signature detection for .xls, HTML table selection, culture inference, header-row autodetection, TMDL validation before commit, and the closed-project requirement. This goes far beyond the sparse annotations.

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

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

The description is long but appropriately structured, starting with the main purpose and then covering edge cases using clear labels and bold emphasis. Each paragraph adds meaningful operational detail, though it could be tightened by moving less common edge cases into optional notes.

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 highly complete for a tool with complex file-handling behavior, covering formats, errors, validation, and dry-run output. It does not explain the overwrite parameter or table naming/description semantics, and it relies on the output schema for return-value details, which is acceptable but leaves minor 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%, so the description carries the burden for parameter meaning. It effectively explains path, sheet, culture, dry_run, table_id, skip_rows, and format-related parameters. However, overwrite, table_name, description, and request_id are not described, leaving gaps.

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

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

The description clearly states the tool loads a file into the model with a specific verb and resource: 'Carga un archivo al modelo'. It distinguishes itself from sibling pbi_add_table_from_source by emphasizing file input support (.csv, .xlsx, .json, etc.) and the Power Query-like pipeline.

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: supported file types, required closed project, dry-run mode, and special handling for .xls/HTML files. It does not explicitly name alternatives like pbi_add_table_from_source, but the scope is well-defined enough to avoid confusion.

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?

This description goes far beyond the annotations (all false) by disclosing critical behavioral details: the credential workflow (first refresh must be completed by a human in Desktop), the fact that the table exists without data until then, that the server cannot verify the connection, and that TMDL requires a closed project. The transparency is exceptional and directly manages user expectations.

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

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

The description is well-structured: a one-line purpose, bullet-like breakdown by source type, a bolded key requirement, and a clear warning about credentials. It is compact for the complexity involved, uses formatting (backticks, bold) to aid scanning, and every section earns its place without 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 14 parameters and no schema descriptions, this description is remarkably complete. It covers the main source types, parameter relationships, required fields, the credential caveat, and the TMDL dependency. Since an output schema exists, the lack of return-value explanation is acceptable. Only minor parameters like dry_run and overwrite are left undocumented, but the core behavior is fully covered.

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

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

Despite the input schema having 0% description coverage, this description explains the meaning and constraints of many parameters: source values, server/database/schema/source_table/native_query for sql/postgres, odata URL pointing to entity set, web_json URL plus json_path, and the required columns array with its rationale. It does not cover dry_run, overwrite, request_id, or description, but the most operationally significant parameters are well documented.

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 clear, specific statement: 'Crea una tabla apuntando a una BASE DE DATOS o API externa.' It names the action (create table) and the resource (external database or API), and then details supported source types, distinguishing it from sibling tools like pbi_add_table_from_file.

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: when adding a table from a database or API. It also gives important usage prerequisites, such as 'columns is mandatory' and the TMDL requirement that the project be closed in Desktop. It doesn't explicitly name alternative tools or when not to use it, but the source-specific breakdown effectively communicates the intended use cases.

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

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

The description adds the deterministic property (same input yields same output), which is not in annotations. However, it does not disclose side effects, whether the operation modifies the report, or any permission requirements. Annotations are sparse but not contradicted.

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 very short and front-loaded with the main purpose in the first line. The additional notes on edge values and determinism are useful, but the brevity omits necessary parameter 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?

Given 4 params, no enums, no effective annotations, and 0% schema coverage, this description is under-specified. It does not explain the relationship with sibling layout tools, what happens to visual positions, or any operational context like return values or error behavior.

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 explain parameters, but it only documents `edge` with valid values. `page`, `visual_ids`, and `request_id` are left unexplained, relying on inference from the tool 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 clearly states the tool aligns multiple visuals by an edge, listing specific edge options (left, right, top, bottom, center_h, center_v). This distinguishes it from sibling tools like distribute or arrange, which have different alignment logic.

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 edge-based alignment but provides no explicit guidance on when to choose this over pbi_arrange_visuals, pbi_distribute_visuals, or pbi_normalize_page_layout. No alternative tools are mentioned or exclusions provided.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds a list of concrete quality checks, which provides useful context. However, it does not disclose additional behavioral traits such as how results are returned, model loading requirements, or performance implications.

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: the first sentence summarizes the core purpose, and the second sentence is a compact list of checks. Every sentence earns its place with no 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?

The output schema exists, so return value details are not necessary. The description provides a solid list of checks, but it omits parameter semantics and usage context, and it does not clarify how this tool relates to similar audit/diagnostic siblings. Given the tool's complexity, this is a moderate gap.

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

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

The single parameter 'source' has a default 'live' but no schema description, and the tool description does not mention or explain it. With 0% schema description coverage, the description fails to compensate or add any meaning to the parameter, leaving agents guessing about valid values or behavior.

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 detects typical model quality problems ('Detecta problemas tipicos del modelo (calidad)') and lists specific checks (measures without folder, long DAX, bidirectional/inactive relationships, calculated columns, visible IDs, missing calendar). This is a specific verb+resource and gives concrete scope, though it does not explicitly differentiate from overlapping siblings like pbi_audit_model.

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

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

There is no guidance on when to use this tool versus alternatives. With many sibling tools for auditing (pbi_audit_model, pbi_health_check, pbi_diagnose_data), the description only states what it checks, not when to choose it over others or what prerequisites 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?

Beyond annotations (destructiveHint=true), the description provides meaningful behavioral context: each action uses transaction/verification/rollback, failures are reported without stopping others or hiding them, and confirm=true is required—all useful for safe invocation.

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 concise sentences, front-loaded with the main action and a critical prerequisite; no filler.

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

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

With output schema present and annotations covering destructive/read-only, the description adds essential failure-handling behavior and a guard condition. Missing request_id semantics and action structure detail, but overall adequate for a complex destructive operation.

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

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

Schema coverage is 0%; the description gives semantic weight to the 'actions' parameter by sourcing it from pbi_plan_audit_fixes and to 'confirm' by making it a mandatory gate, but request_id is never explained and the open-ended action objects are not detailed.

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 'Aplica las acciones devueltas por pbi_plan_audit_fixes' (Applies the actions returned by the plan tool), clearly identifying a verb (applies), a resource (actions), and the source, distinguishing it from sibling pbi_plan_audit_fixes and other tools.

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

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

It specifies a prerequisite 'Requiere confirm=true' and implicitly situates the tool after pbi_plan_audit_fixes, but doesn't explicitly name alternatives or when-not-to-use.

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

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

Annotations already indicate a write operation (readOnlyHint=false), and the description reinforces this by stating 'Escribe el tema' (writes the theme) and 'Escribe en el informe (PBIR)' (writes to the PBIR report). It goes beyond annotations by specifying the exact side effects: modifying report.json, returning canvas/grid/typographic scale, and the recommendation to close the project. This gives the agent useful behavioral context about what changes and what to expect.

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

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

The description is well-structured in three short paragraphs: the first gives the main action and output, the second details the write and return values, the third offers a practical warning. Every sentence adds value, there is no redundant or filler content, and the key information is front-loaded. It is concise without sacrificing necessary detail.

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

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

The presence of an output schema means the description doesn't need to detail return types, but it still mentions the return values (canvas, grid, typographic scale) as added context. It covers the side effect (writing report.json) and a critical prerequisite (closing the project in Power BI Desktop). It does not mention error scenarios, prerequisites beyond the closed project, or how to obtain a valid system value, but given the tool complexity and schema richness, the description 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?

The input schema has only two parameters (system, request_id) with zero descriptions, so the description must compensate. The name and description together make it clear that 'system' refers to the design system to apply, but the description does not define the expected format, where to obtain valid values, or any default behavior. It indirectly points to the existence of design systems (sibling pbi_list_design_systems), but this is not explicit. The semantics are inferable but not fully specified, meriting a mid-range score.

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: 'Aplica el sistema al informe' (applies the system to the report) and immediately mentions the output: 'devuelve su rejilla' (returns its grid). It also mentions writing the theme and declaring it in report.json, and it distinguishes itself from the similar sibling pbi_compose_page by noting that manually placed items should use the same guides. This is a specific verb+resource+output, fully differentiated from 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 practical context: it should be used before manually placing items, as it ensures consistency with pbi_compose_page. It also provides a concrete operational guideline: 'conviene tener el proyecto CERRADO en Power BI Desktop' (it is advisable to have the project closed in Power BI Desktop). While it doesn't explicitly say 'do not use when...', the reference to pbi_compose_page and the manual placement workflow imply the intended moment of use, making the guidance clear but not exhaustive.

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

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

The description contradicts the annotations: destructiveHint=false, yet sync_mode=replace 'ademas elimina los visuales ausentes' (deletes absent visuals). This is a direct conflict, forcing a score of 1 per the contradiction rule, despite otherwise rich disclosure of outcomes, id preservation, and dry_run semantics.

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

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

The description is well-structured and front-loaded: core purpose first, then outcomes, then per-parameter explanations. Each sentence adds necessary information; the formatting with backticks and line breaks improves readability without bloat.

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

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

For a complex tool, the description covers outcomes, parameter behaviors, interaction referencing/types, and dry_run. It omits seed and request_id, and the spec object's schema is not detailed, but the presence of an output schema reduces the burden for return-value explanations. Overall strong, with minor 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?

With schema description coverage at 0%, the description compensates by explaining page (id/name, defaults), sync_mode (merge vs replace, conservative default), interactions (referencing by position/id/title, types), and dry_run (plan_token, no write). However, seed and request_id are not mentioned, and spec's full structure is only partially addressed.

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: 'Materializa el spec como una pagina PBIR, en UNA transaccion.' It clearly distinguishes the tool's role as the writer (apply) versus preview/validate siblings, and enumerates four explicit outcomes (create, update, no_change, conflict).

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 context: it applies a page spec transactionally, with dry_run as a safe planning mode, and explicitly mentions pbi_apply_plan as a follow-up. It does not explicitly exclude alternatives or state when not to use, but the usage context is well-defined.

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

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

Beyond the destructiveHint annotation, the description adds critical behavioral details: it verifies project state before applying, rejects changes if state differs, requires confirm=true, and explains the historical default change. This adds significant value beyond annotations.

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

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

The description is moderately long but well-structured: it opens with the main purpose, then safety checks, then param clarification, then confirmation requirement with rationale. Every sentence adds value without redundancy.

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

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

Given the output schema exists and annotations cover destructive nature, the description sufficiently covers the safety mechanism, the optional parameter, and the confirmation gate. It could elaborate on error scenarios beyond plan_operation_mismatch, but overall it's complete for its 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?

Schema description coverage is 0%, so the description must compensate. It explains expected_operation and confirm explicitly, but plan_token and request_id are not described. plan_token is inferable as the plan identifier, but request_id remains undocumented. Partial compensation.

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 applies a plan calculated with pbi_plan_change or a dry_run. It distinguishes itself from sibling tools by specifying the source of the plan and the additional verification step, making its purpose distinct.

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

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

It implies usage after plan generation and emphasizes the need for confirm=true. It does not explicitly name alternatives, but the context (plan_change vs apply) is clear. The expected_operation parameter is explained as a safety mechanism.

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 all annotations false, the description carries the full burden and excels. It reveals file writes to StaticResources/RegisteredResources and report.json, the silent-ignore failure mode, deep-merge semantics for patch, loss of color-blind ordering when using data_colors, requirement for the project to be closed, and backup/replacement behavior. This is far beyond typical descriptions.

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 a one-sentence purpose, then organized by parameter with clear, dense explanations. Every sentence adds value, covering file paths, failure modes, merge semantics, and prerequisites, without wastefulness or repetition.

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 seven parameters, no required fields, and complex file-modifying behavior, the description covers all critical context: file operations, prerequisites, parameter interactions, replacement warnings, and backup recovery. An output schema exists, so return values are not needed. The only minor gap is the unexplained request_id, but it does not hinder effective use.

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

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

Schema coverage is 0%, so the description must compensate. It thoroughly explains preset, data_colors, name, theme_json, fonts, and patch, including precedence and interaction (e.g., theme_json overrides preset; fonts and data_colors apply on top). The only omission is request_id, but that is a minor, likely common parameter, and the overall compensation is outstanding.

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 line explicitly states the tool's core function: 'Aplica un tema de colores al informe .pbip activo' (Applies a color theme to the active .pbip report). It clearly names the resource type (.pbip report) and the action (apply theme), distinguishing it from sibling tools like pbi_list_themes and pbi_apply_design_system.

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 extensive guidance on parameter selection: use preset for presets, theme_json for full custom themes, fonts for typography, and patch for partial changes. However, it does not explicitly contrast with alternative tools such as pbi_apply_design_system, so it misses clear 'when to use this vs. that' tool-level 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?

Annotations provide no safety hints (all false), so the description carries the burden. It discloses a default behavior (visual_ids defaults to all) and the structure of custom positioning, but it does not mention reversibility, side effects, or required permissions. This is partial transparency for a mutation tool.

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

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

The description is highly concise: two sentences plus a compact parameter reference. It front-loads the main action and uses a clear, structured format for parameter details. No unnecessary words 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 conveys the core action and main parameters, but it does not explain the meaning of 'dashboard' or 'executive_summary' layouts, the 'canvas' and 'spacing' parameters, or potential side effects. Since the output schema exists, return values need not be described, but the missing parameter context leaves the description partially incomplete for a 7-parameter mutation 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?

The description adds valuable semantics for 'layout' (enumerating grid, dashboard, executive_summary, custom) and 'visual_ids' (optional subset, defaults to all) and 'custom' (map format). However, with 7 parameters and schema coverage at 0%, it fails to explain 'page', 'canvas', 'spacing', and 'request_id', leaving significant gaps.

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

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

The description clearly states the tool's function: 'Reorganiza los visuales de una pagina' (reorganizes the visuals of a page). It specifies the resource (visuals on a page) and the action (reorganize), and lists layout options. However, it does not explicitly differentiate from sibling tools like pbi_align_visuals or pbi_distribute_visuals, so it misses full distinction.

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 by explaining layout options and the optional visual_ids subset, but it provides no explicit guidance on when to use this tool versus alternatives (e.g., align, distribute, normalize). There are no stated prerequisites or exclusions, so guidance remains implicit rather than explicit.

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

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

The description discloses that each finding includes specific fields and that evidence always accompanies findings, meaning heuristics are not presented as certainty. This goes beyond the readOnlyHint annotation by explaining the epistemic behavior of results.

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 sentences cover purpose, output shape, and core parameters with no filler. Front-loaded with the primary action.

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

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

The output schema is present and the description covers the main result structure, but the `source` parameter is unexplained and no sibling differentiation is given. For a 3-parameter tool with zero schema descriptions, this leaves some 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 description explains the meaning of `rules` and `min_severity`, including the accepted values for min_severity. The `source` parameter is left undocumented, and with 0% schema coverage, this is a 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 'Audita el modelo semantico' with a specific verb and resource, clearly identifying the tool's function. However, it does not differentiate from sibling audit tools like pbi_audit_project or pbi_audit_report_only.

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

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

The description references pbi_list_audit_rules for the rules parameter, providing a path to discover valid rules. It does not state when to use this over pbi_audit_project or pbi_audit_report_only, so usage guidance is only implicit.

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

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

Annotations are sparse, but the description discloses a real side effect: when `formats` is provided, it 'escribe tambien esos informes en outputs/ y devuelve sus rutas'. It also explains compact mode's structural changes and confirms that written reports are always complete. This goes beyond the annotations and gives the agent a clear behavior model.

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 tightly packed with useful information: outcome summary, file side effects, filtering, and compact-mode semantics. It is front-loaded and every sentence earns its place, though the compact-mode explanation is dense and could benefit from light structuring.

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 4-parameter optional tool with an output schema, the description covers the main return content, file outputs, filtering, and compact behavior. It is complete enough for an agent to call it effectively; the missing severity levels and explicit sibling routing are the only 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%, so the description carries the burden. It explains `formats` with allowed values, `compact` in detail, and says `rules` and `min_severity` acotan (narrow) the audit. The only real gap is that it doesn't list the allowed severity values for `min_severity`, so the parameter semantics are strong but not complete.

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

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

The description starts with 'Auditoria integral: modelo semantico + informe + layout', which clearly names the verb, resource, and scope. It also differentiates itself from sibling pbi_audit_report_only by emphasizing the full project audit including layout, not just the report.

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

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

The phrase 'Auditoria integral' establishes that this is the complete audit tool, and the notes about automatic correction rules and compact mode give practical filtering context. However, it never explicitly says 'use this instead of X' or names alternative tools like pbi_audit_model or pbi_audit_report_only, so the routing is clear but not explicit.

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

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

Annotations declare readOnlyHint=true, and the description adds the specific audit categories, giving the agent a clear picture of what will be inspected without contradicting the read-only hint.

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 establishes the tool's narrow purpose, the second lists the exact audit areas. 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?

Given zero parameters and a read-only annotation, the description sufficiently covers the tool's behavior and scope. The output schema (present) handles return value details, so the description need not elaborate further.

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 accepts no parameters, so the description inherently covers all input needs; no parameter 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 states it audits only the PBIR report, excluding semantic model rules, and lists specific audit checks (empty pages, visuals without title, broken fields, duplicates, canvas sizes, page geometry). This clearly distinguishes it from siblings like pbi_audit_model.

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

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

It explicitly says 'solo el informe PBIR (sin las reglas del modelo semantico)' indicating the tool is scoped to report-only audits, providing clear context for when to use it. It doesn't name alternative tools but its scope exclusion is evident.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds that backups are timestamped and returns the path. It does not disclose where backups are stored, whether they overwrite, or if an active project must be open, leaving gaps for a mutation tool.

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

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

Two sentences: first states purpose, second lists options and return value. Front-loaded, no fluff, and appropriately sized.

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 output schema likely covers the return path, and the core action is clear. However, missing context about backup location, project prerequisites, and interaction between mode and scope reduces completeness for safe and effective invocation.

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

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

With 0% schema description coverage, the description must explain parameters. It merely lists mode values (folder|zip) and scope values (report|model|both) without defining them, and request_id is completely undocumented. This is insufficient for correct parameter use.

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

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

The description clearly states the tool's purpose: creates a timestamped backup of the active .pbip project. It uses a specific verb ('Crea') and resource, distinguishing it from sibling tools like pbi_convert_pbix_to_pbip or pbi_purge_backups.

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 (backing up a project) but does not explicitly state when to use it or mention alternatives. It gives no 'when not to use' guidance, though the self-explanatory backup context provides some implicit direction.

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

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

The description outlines the multi-step process (analyze, compose spec, calculate layout, preview, apply transaction, verify) and explains the dry_run default behavior. Annotations are all false and add little, so the description carries the burden and does so effectively, though it could detail failure handling or what 'applies' entials.

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: three sentences with a clear opening purpose, a workflow overview, and a critical default behavior note. Every sentence earns its place with no fluff or repetition.

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 (multi-step dashboard building), the description provides a high-level workflow but omits what 'objetivo' maps to in parameters, preconditions, or expected output. The presence of an output schema mitigates the need for return value details, but more guidance on how to phrase the objective would improve 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 explicitly explains dry_run and references preset, but leaves name, measures, seed, category, and request_id undefined. The phrase 'desde un objetivo' vaguely implies name/measures define the goal, but this is not concrete enough for reliable parameter understanding.

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

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

The description clearly states it builds a complete dashboard from an objective, not from primitives. This distinguishes it from sibling tools like pbi_create_visual and pbi_compose_page, which are lower-level. The verb 'Construye' and resource 'dashboard completo' are 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 implies usage for high-level dashboard creation when there is a defined objective, contrasting with primitive operations. It does not explicitly name alternative tools or exclusions, but the 'no desde primitivas' phrase provides clear context for when this tool is appropriate.

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

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

Annotations provide no meaningful behavioral hints (all false), so the description must carry the burden. It usefully discloses that the tool validates measures and will warn instead of generating a nonsense page. However, it does not mention the behavior of the dry_run parameter, whether the tool modifies an existing report/page, or other side effects, leaving 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 short sentences in Spanish, front-loaded with the page type and immediately followed by key validation behavior. Every sentence adds value and there is 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?

Despite having an output schema, the tool has 6 parameters with no schema descriptions and no explanation of prerequisites or how parameters like `dry_run`, `seed`, or `category` affect the result. The description covers only the `measures` parameter and validation behavior, which is not enough for reliable invocation in a large sibling-tool context.

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

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

Schema description coverage is 0%, so the description must compensate for 6 undocumented parameters. It clarifies the `measures` parameter by listing expected types, but it leaves `name`, `seed`, `dry_run`, `category`, and `request_id` completely unexplained. This is insufficient for an agent to correctly set all parameters, especially the critical `dry_run` flag.

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

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

The description clearly identifies the tool as generating an EVM page and specifies the expected measure types (PV, EV, AC, CPI, SPI). The phrase 'generar una página' explicitly states the action, and the EVM-specific scope distinguishes it from sibling tools like pbi_build_executive_page.

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 context for use: it should be used when EVM measures are present, and it warns if it cannot recognize them rather than producing a meaningless page. It does not name alternative tools or explicitly state when not to use it, but the usage context is evident.

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

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

The annotations show readOnlyHint=false, but the description does not clarify what side effects building a page has (e.g., whether it creates a new page, overwrites an existing one, or requires specific model state). No behavioral traits beyond the annotation are 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?

The description is extremely short, but this is under-specification rather than conciseness. It lacks essential information about the tool's behavior and parameters, so the single sentence does not earn its place as an adequate 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?

Given the complexity of a build tool with 6 parameters and no schema coverage, the description is severely incomplete. It does not explain what the page building entails, how parameters affect the output, or any dependencies, making it insufficient for an agent to invoke the tool correctly.

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

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

With 0% schema description coverage and 6 parameters, the description fails to explain any of them. It mentions 'fila de KPIs' and 'grafico protagonista' but does not connect these to the 'measures' or 'category' parameters, leaving the agent unable to infer parameter meanings.

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 'Pagina de resumen ejecutivo: fila de KPIs y grafico protagonista' gives a vague idea that the tool produces an executive summary page with a KPI row and a featured chart, but it uses a noun phrase rather than a clear verb, so it doesn't explicitly state what the tool does. It implies building, but doesn't distinguish from sibling tools like pbi_build_dashboard or pbi_compose_page.

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

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

There is no guidance on when to use this tool compared to alternatives. No context, prerequisites, or exclusions are provided, leaving the agent without direction on selecting it over similar page-building tools.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context by detailing what information the tool reveals (live layer status, write permissions, engine version constraints) and that it provides reasons for unavailable capabilities, which goes beyond the structured metadata.

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: first sentence states the core purpose, second elaborates on specifics. Every sentence carries useful information with no redundancy or 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?

Given the tool's simplicity (no params) and the presence of an output schema, the description adequately covers its purpose and key behavioral facets. It could mention what happens when the live layer is unavailable, but the output schema likely covers such details.

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 coverage is 100%, so there is nothing to explain. With no parameters, the baseline is 4, and the description appropriately focuses on the tool's output rather than input semantics.

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: to report what capabilities are currently available and what are not, with reasons. It specifies concrete aspects (live layer availability, .pbip writability, engine-version-dependent capabilities), distinguishing it from sibling tools like pbi_report_capabilities which likely focus on report-specific capabilities.

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

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

Explicitly says an agent should consult this tool before planning, giving a clear when-to-use directive. It does not mention when not to use it or name alternative tools, but the context is strong enough to guide appropriate usage.

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

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

Annotations declare readOnlyHint=true, and the description adds context: it is a structural and honest check, explicitly stating that key uniqueness/orphans are not checked when data are incomplete, and that the response communicates this via `not_checked`. It also reveals the output field `suggested_critical_fields`, providing behavior beyond the annotation.

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 structured into two clear mode-based paragraphs, with the main purpose front-loaded. It is somewhat dense but every sentence contributes meaning, referencing related tools and limitations without fluff.

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

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

Given the two-mode complexity and the existence of an output schema, the description covers the main use cases, limitations, and integration with pbi_diagnose_data and pbi_define_brief. It does not explain `request_id`, which is a minor completeness gap, but overall it provides sufficient context for an agent to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must explain parameters. It clarifies `source_path` as the mode selector and `dataset` as an add-on to `source_path`, but it does not mention `request_id` at all. This leaves one of three parameters undocumented, a notable gap.

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

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

The description clearly states it validates against the port contract, either an incoming file or the active model. It distinguishes itself from pbi_diagnose_data by explaining the different scope (pre-load structural checks vs. full data checks). The verb 'Valida' is specific and the resource is well-defined.

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 explicit usage conditions: with `source_path` (+ `dataset`) for pre-load file validation, without `source_path` for model validation. It also names an alternative (pbi_diagnose_data) for key uniqueness/orphans and the follow-up tool pbi_define_brief, forming a clear workflow.

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

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

Beyond the destructiveHint annotation, the description details the destructive consequences (unsaved changes lost, including refreshed data in .pbip), the required confirm=true, the verification of process identity, and the behavior when the file isn't open (does nothing, reports was_open: false). This adds substantial behavioral context that the annotation alone doesn't provide.

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

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

The description is efficient and well-structured: starts with the core purpose, then provides context, behavior, and parameter nuances. Each sentence adds value without redundancy, making it both concise and informative.

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

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

Given that an output schema exists (not shown but indicated), the description covers all necessary aspects: purpose, usage context, destructive behavior, parameter meaning, and expected outcomes (verified_closed, was_open). It is complete for a tool of this complexity.

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

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

With 0% schema description coverage, the description compensates by explaining the key parameters: path/pbip_path can be omitted to target the active project, and confirm must be true for destructive operation. It doesn't mention request_id, but that may be a generic parameter. The most critical parameters are well-documented.

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: closing the Power BI Desktop instance serving a specific project. It uses a specific verb ('Cierra') and resource ('instancia de Power BI Desktop que sirve ESE proyecto'), and distinguishes itself from sibling tools like pbi_open_in_desktop by focusing on the closing action.

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 strong contextual guidance: it explains that writing TMDL requires Desktop closed and that this tool fills the gap. It also mentions that the path can be omitted to close the active project. However, it does not explicitly name alternative tools or state when not to use it, though the context is clear enough.

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

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

The readOnlyHint annotation already indicates a safe read operation, so the description's added context—listing dependency types and the 'tells if something breaks' behavior—provides meaningful transparency beyond the annotation. No contradictions found.

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 concise sentences, front-loaded with the core purpose and followed by a practical use case. Every word earns its place without 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?

The description covers the essential use case and dependency types, and an output schema likely documents return values. It lacks details like interpretation of results or limitations, but given the schema and annotations, it is sufficiently complete for 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?

With 0% schema description coverage, the description must explain parameters, but it only indirectly references 'column' and 'table' without detailing them. The 'source' parameter is not mentioned at all, leaving ambiguity about its purpose (e.g., live vs. other sources).

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 identifies what uses a column—measures, calculated columns, relationships, and hierarchies—which is a specific verb+resource. It also distinguishes itself from sibling tools like pbi_measure_dependencies by focusing on column dependencies rather than measure dependencies.

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

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

The description explicitly says to use it before hiding or deleting a column to check if anything breaks, providing a clear when-to-use scenario. It doesn't mention when not to use it or name alternatives, but the context is specific enough for agents to select it appropriately.

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?

readOnlyHint=true already signals a safe read operation, and the description adds behavioral detail by specifying that it lists tables and measures that exist only on one side and measures whose DAX differs. No contradictions with annotations; the description enriches the safety profile with specific comparison behavior.

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

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

The description is two concise sentences. The first sentence states the core action, and the second explains the use case and what it outputs. There is no redundant or filler content.

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

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

Given the tool has no parameters, an output schema, and read-only annotations, the description covers the essential aspects: what is compared, what is listed, and when to use it. It is complete for its relatively simple scope and leaves no significant ambiguity about its behavior.

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 baseline is 4. The description does not need to provide parameter semantics, and the schema covers 100% of parameters (none), making this adequate.

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

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

The description clearly states it compares the live model with the TMDL on disk, which is a specific verb+resource+comparison. It distinguishes itself from siblings by focusing on unsaved changes in memory versus the disk state, and explicitly mentions what it lists (tables, measures, DAX differences).

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 a clear use case: 'Util para saber si hay cambios en memoria sin guardar' (useful for knowing if there are unsaved changes in memory). It does not explicitly name alternatives or exclusion criteria, but the context of comparing live vs. disk is clear and sufficient.

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

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

The description discloses that the tool writes (unless dry_run=true), that the server decides geometry, that text color comes from the report theme (not the system), that the composition order is fixed for coherence, and that it warns if content doesn't fit. It also explains the dry_run behavior and that it follows the same validation/transaction as pbi_apply_page_spec. This goes far beyond the minimal annotations, which provide no read-only or idempotency guarantees.

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

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

The description is well-organized with a clear introductory sentence, bullet-style explanations of each parameter, and a short rationale for design decisions. It is moderately long but every section adds value. The structure aids readability and front-loads the main purpose before diving into details.

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

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

Given the tool's complexity (10 parameters) and the presence of an output schema, the description sufficiently covers the core behaviors and parameter semantics. It explains dry_run's return value and the fixed composition order, but doesn't describe the non-dry-run response in detail. However, the output schema likely fills that gap.

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

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

Despite the 0% schema description coverage, the description thoroughly explains the meaning and expected structure of key parameters: title/subtitle, kpis, hero, supports, and detail, providing example JSON formats. It also describes dry_run's purpose. The only parameters not explicitly described are system, page_name, and request_id, but these are likely straightforward or auxiliary.

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 'Compone una pagina entera sobre la rejilla del sistema de diseno' (composes an entire page on the design system grid) and explains the intention-driven approach. This distinguishes it from sibling tools like pbi_apply_page_spec (which applies an explicit spec) and pbi_create_page_from_spec (which creates from a specific spec), as it focuses on high-level page composition with automatic geometry.

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 conveys when to use this tool: when you want to compose a page by describing intention and letting the server decide geometry. It mentions dry_run for preview without writing and references pbi_apply_page_spec for validation/transaction path, but does not explicitly compare to alternatives or state when not to use it.

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

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

Beyond the sparse annotations (readOnlyHint=false, destructiveHint=false), the description discloses significant behavioral traits: it opens .pbix files in Power BI Desktop, may reuse an open session, closes Desktop if it opened it, never modifies the original file, and reports dropped items. This directly addresses side effects and performance implications, providing rich context beyond what the annotations convey.

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 every sentence serves a purpose: purpose, process, warnings, parameters, and output. It is well-structured into paragraphs and uses inline code for parameter names. It front-loads the main function and then details caveats and specifics without redundant 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?

The description is quite complete for a complex tool: it explains the conversion process, the necessity of opening Desktop, behavior with open sessions, original-file preservation, required parameter conditions, and the output (warnings/dropped items). An output schema exists, so return values need not be spelled out. However, it does not cover all parameters (e.g., overwrite, desktop_timeout), which are relevant for a full understanding, leaving minor 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?

With schema description coverage at 0%, the description must compensate for parameter meanings. It explains key parameters like path (file or folder, recursive), out_dir (subfolder per report), include_model (skip Desktop), dataset_connection_string (required for live connections), and close_desktop (implicitly). However, it omits semantics for overwrite, project_name, request_id, and desktop_timeout, which are not self-explanatory despite their titles. The partial coverage leaves gaps.

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

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

The description opens with a specific verb and resource: 'Convierte uno o varios .pbix en proyectos .pbip (PBIR + TMDL).' It clearly defines the tool's purpose and differentiates it from sibling tools like pbi_create_pbip_project (which creates projects from scratch) and pbi_inspect_pbix (which inspects files).

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 on when to use the tool: when you need to convert .pbix files into .pbip projects. It also notes conditional usage (e.g., include_model=false to skip Desktop processing, dataset_connection_string required for live connections). However, it does not explicitly mention alternatives or exclusions, such as when to prefer pbi_create_pbip_project over this tool.

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

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

Las anotaciones no aportan información porque todos los hints son false. La descripción añade detalles cruciales: no se copia el texto del título (contenido) y el cruce de tipos es rechazado. Esto va más allá de simplemente decir 'copia' y ofrece contexto sobre límites y riesgos.

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?

La descripción es breve y bien estructurada: una frase principal, una aclaración sobre el título y una restricción con justificación. No hay relleno ni redundancia; cada frase aporta información útil.

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?

Describe la acción principal, el matiz del título y la restricción de tipo, pero no aclara si el copiado puede ser entre páginas distintas, a pesar de que los parámetros source_page y target_page lo sugieren. Tampoco menciona el comportamiento ante errores. Dado que existe un esquema de salida, la falta de descripción del retorno es aceptable.

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?

La cobertura del esquema es 0% y la descripción no menciona ningún parámetro concreto. No explica cómo identificar source_page, source_visual, target_page o target_visuals ni qué formato deben tener los identificadores, dejando al agente sin información adicional.

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?

La descripción comienza con 'Copia el formato de un visual a otros DEL MISMO TIPO', usando el verbo específico 'copia' y el recurso 'formato de un visual'. La restricción 'DEL MISMO TIPO' distingue claramente la herramienta de otras como pbi_duplicate_visual o pbi_set_visual_title.

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?

Se indica explícitamente cuándo no usar: 'Copiar entre tipos distintos se rechaza', lo que delimita el contexto de uso. No se nombra una alternativa directa, pero la advertencia de que Power BI podría rechazar el informe aclara los riesgos.

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?

Description discloses that the tool writes the bookmark file and updates the index, warns that Power BI won't show the bookmark without the index, and mentions the return value ('usage'). This adds behavioral context beyond the annotations, which already indicate a non-read-only operation. No contradiction with annotations.

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

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

The description is a compact paragraph that front-loads the purpose, then explains side effects, param hints, and return value. Every sentence adds value with 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 9 parameters and a mutation operation, the description covers the core purpose and key side-effects but omits several parameter semantics (e.g., overwrite, suppress_data). The output schema likely documents the return value, but parameter gaps reduce 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?

The schema has 0% description coverage, so the description carries the burden. It explains `page`, `filters`, and `target_visuals` with useful detail, but leaves `display_name` (required), `overwrite`, `name`, `request_id`, `suppress_data`, and `suppress_display` unexplained. This is a partial compensation, not complete.

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 creates a bookmark ('Crea un marcador') and defines what a bookmark is (a report state to return to via a button). It distinguishes from siblings like pbi_list_bookmarks and pbi_delete_bookmark by describing the creation and index-writing behavior.

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 by explaining the creation workflow and the dependency on the index, but it does not explicitly name alternatives or exclusions. The context is sufficient to infer this is the creation tool among bookmark-related siblings.

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

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

The annotations are all false, so they provide no safety hints. The description adds important behavioral context by disclosing that the tool writes to TMDL and requires the project to be closed in Power BI Desktop. However, it does not disclose other behavioral traits such as whether overwriting is destructive or what side effects occur beyond the TMDL write.

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 structured across three short sentences. The first sentence gives the purpose, and the subsequent sentences clarify key parameters and a critical prerequisite. It is not overly verbose, though it could benefit from clearer separation of parameter details.

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

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

Given the tool's complexity (11 parameters, no schema descriptions, no annotation hints), the description is incomplete. It covers the core purpose and two parameter semantics, plus a prerequisite, but does not explain the return value/output, the remaining parameters, or the broader model modification implications. This is insufficient for an agent to fully understand the tool's capabilities and side effects.

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 explains two parameters (data_type and summarize_by) with meaningful detail, but there are 11 parameters total. It does not describe the required parameters table, name, and expression in detail, nor the optional ones like overwrite, is_hidden, format_string, and display_folder. This leaves many parameters without adequate semantic guidance.

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 creates a calculated column (DAX) in a table of the .pbip model, using a specific verb and resource. It distinguishes from sibling tools like pbi_create_measure and pbi_create_calculated_table by specifying 'column' and the model context.

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

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

The description does not explicitly mention when to use this tool versus alternatives like pbi_create_measure or pbi_create_calculated_table. It does provide a key usage constraint—the project must be closed in Power BI Desktop—which gives some guidance on prerequisites, but lacks explicit when-to-use or when-not-to-use instructions.

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

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

The description goes beyond the minimal annotations by disclosing that column inference executes the DAX against the open model and that the tool writes TMDL requiring a closed project. This adds meaningful operational context. However, it does not explain behavior of the 'overwrite' parameter or potential side effects of executing the expression.

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 but information-dense, with each sentence adding value: use case, technical mechanism, and prerequisite. No fluff or repetition, and key details are front-loaded.

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, the description covers essential operational constraints (model state, project state) and the core behavior. It does not describe return values, but an output schema exists. Missing details about overwrite semantics and error conditions are gaps, but overall it is fairly complete for a knowledgeable agent.

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

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

Schema description coverage is 0%, so the description carries full burden. It explains the 'columns' parameter well (inferred by executing DAX if not provided), but leaves 'overwrite', 'description', and 'request_id' unexplained. With 6 parameters and only one meaningfully detailed, compensation is incomplete.

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

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

The description starts with a specific verb+resource: 'Crea una tabla calculada (DAX) en el modelo .pbip.' This clearly distinguishes it from siblings like pbi_create_calculated_column or pbi_create_measure. The use-case explanation (unpivoting columns to rows) further clarifies its unique role.

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 a concrete use case ('diez metricas guardadas en diez COLUMNAS en vez de en filas') and explicit operational requirements (model open/selected for column inference, project closed for TMDL write). While it doesn't name alternative tools, the context makes appropriate usage clear.

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

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

With all annotations set to false, the description carries the burden of behavioral disclosure. It reveals that the operation writes TMDL, requires a closed project, and deliberately preserves the order of levels without sorting or deduplication. Missing overwrite behavior and error handling, but the disclosed traits are meaningful and non-obvious.

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 purpose sentence, a focused parameter note, and a prerequisite. It has no wasted sentences, though the phrase 'porque es informacion' is slightly awkward and could be tightened. Overall, it is concise and well structured.

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

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

The description captures the core invocation requirements: same-table columns, correct level order, and a closed Power BI project. However, with seven parameters and zero schema descriptions, it leaves overwrite semantics and optional fields under-specified. An output schema exists but does not compensate for these parameter knowledge 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%, so the description must compensate by explaining parameter meanings. It does this only for `levels`, which is richly explained with ordering and preservation semantics. The remaining six parameters—`table`, `name`, `overwrite`, `request_id`, `description`, and `display_folder`—are left to name-based inference, which is insufficient at this coverage level.

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 'Crea una jerarquia sobre columnas de la misma tabla', which clearly identifies the verb (create) and resource (hierarchy on columns of a table). It does not explicitly distinguish itself from sibling creation tools, but the hierarchy object type is unambiguous enough to avoid confusion with measure or column creation.

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

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

The description gives a concrete prerequisite: 'requiere el proyecto CERRADO en Power BI Desktop' and specifies the required ordering of levels from high to low granularity. It does not mention when to choose an alternative tool, but the closed-project requirement and ordering semantics are useful usage 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?

Annotations are present (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds behavioral context beyond them: it states that the custom visual is registered in the report if not already present, and clarifies that the HTML is built in DAX (typically with VARs and CONCATENATEX). This is useful side-effect disclosure, though it doesn't cover all failure modes or behavior on existing visuals.

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

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

The description is concise: two short paragraphs, with the primary purpose front-loaded. The parameter detail is inline and could be better formatted as a list, but it's efficient and free of fluff.

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

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

Given the tool's complexity (5 params, nested position object, output schema present), the description provides key workflow context: the measure is pre-created via pbi_create_measure, the visual registers itself, and the HTML is constructed in DAX. It does not explain page/position details, but for a Power BI-focused audience these are familiar. The output schema likely covers return values, so the description needn't.

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 5 parameters with 0% schema description coverage, so the description must compensate. It only explains html_measure, giving an example, but leaves page, position, title, and request_id undocumented. This is insufficient for a tool where the user must supply page and position correctly.

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: 'Crea un visual "HTML Content"' (creates an HTML Content visual) and explains its function: renders HTML/SVG from a measure. This clearly distinguishes it from generic siblings like pbi_create_visual or pbi_add_custom_visual by naming the exact visual type.

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

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

It explicitly instructs that the measure must be created separately with pbi_create_measure, providing a direct cross-reference to a sibling tool. It also gives an example measure name ('[HTML Panel EVM]'). This gives clear context for when this tool is appropriate, though it does not state explicit 'when-not-to-use' 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?

Annotations only indicate non-read-only and non-idempotent. The description adds rich behavioral details: validation that the table exists and the measure doesn't (unless overwrite), the diff return, and the detailed constraints around mode ('both' disabled, Desktop open/closed requirements). This goes well beyond the annotation information.

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

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

The description is well-structured and front-loaded with the main purpose. Each sentence adds value: validation, mode guidance, data_category example, and diff return. No filler or redundant text.

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

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

Covers preconditions, mode selection, and return behavior, and the output schema handles structure. However, the incomplete explanation of several optional parameters creates some gaps for a 10-parameter 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 coverage is 0%, so the description must compensate. It explains 'mode', 'data_category' with a concrete example, and 'overwrite' semantics. Required parameters (table, name, expression) are self-evident, but optional ones like format_string, display_folder, description, and request_id are not elaborated, leaving partial compensation.

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 'Crea (o reemplaza con overwrite=true) una medida DAX', with a specific verb, resource, and the overwrite behavior. This distinguishes it from sibling tools like pbi_update_measure and pbi_create_calculated_column.

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 clear context on selecting mode ('live', 'pbip', 'auto') and when each is appropriate, including the 'construyendo desde cero' hint. However, it does not explicitly mention alternative tools or exclusions, so it stops short of full when/when-not guidance.

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

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

The description adds useful behavioral context beyond annotations: it clones existing visuals as templates, makes a backup, and auto-arranges visuals when 'position' is omitted. However, it does not disclose what happens if the page already exists or how existing content is affected, leaving some ambiguity.

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 well-structured, with the main purpose in the first sentence and a clear code block for the spec schema. Every sentence adds value, and there is no redundant or vague content.

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

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

Given the nested spec object and zero schema coverage, the description covers most necessary aspects: spec structure, cloning, backup, and layout behavior. It falls short only in explaining the 'rol:refs' field notation and how this tool relates to sibling spec-validation/preview tools, but it remains quite complete for its complexity.

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

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

The schema is opaque for the 'spec' object (additionalProperties true, 0% description coverage), but the description fully documents its internal structure: page_name, canvas, layout enum, and visuals with type/title/fields/position. It also explains the behavioral meaning of omitting 'position', which is essential for correct use.

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 creates a complete PBIR page from a spec, using a specific verb and resource. It distinguishes itself by mentioning spec-driven creation and cloning existing visuals, but it does not explicitly differentiate from sibling tools like pbi_apply_page_spec or pbi_compose_page.

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 pbi_apply_page_spec or pbi_generate_report_page. It only describes the spec format without any exclusions, prerequisites, or alternative recommendations.

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

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

The description discloses key behaviors beyond annotations: it 'deja activo' the project, uses relative paths to avoid machine-specific coupling, includes one page because a report without one won't open, and intentionally omits `sourceQueryCulture` with reasoning. These are meaningful behavioral details that the annotations (all false) do not cover.

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 organized into short paragraphs, each serving a purpose: purpose, workflow, technical rationale, and culture note. It is more detailed than strictly necessary but every sentence earns its place, with no filler or repetition.

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 provides rich rationale for design decisions, but with 9 parameters and zero schema coverage, the missing parameter semantics create a gap. An output schema exists, so return values are covered, but the description should do more to explain how input parameters affect the created project.

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%, yet the description doesn't explain most parameters. It only hints at the culture parameter through the `sourceQueryCulture` discussion, but out_dir, name, width, height, overwrite, page_name, request_id, and open_project remain semantically unexplained. The description adds some context but doesn't compensate for the high parameter count.

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 creates an empty but valid .pbip project: 'Crea un proyecto .pbip vacio pero valido, y lo deja activo.' It also distinguishes this from siblings by framing it as the starting point for a file-path-based workflow, mentioning pbi_add_table_from_file as the next step — a specific verb+resource with clear 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?

It gives clear when-to-use context: 'Es el punto de partida para armar un tablero solo con rutas de archivos' and outlines the intended workflow (create project, load data, compose pages). While it doesn't explicitly state when not to use it (e.g., converting an existing .pbix), the workflow guidance effectively implies its place among alternatives.

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

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

Annotations are all false (no readOnly/opensWorld hints), so the description carries the full burden. It discloses that the tool writes to TMDL ('Escribe en TMDL'), requires the project closed, and explains the ambiguity implications of cross-filtering directions. This adds valuable behavioral context beyond the schema, such as the default safe behavior and the need to justify complex filtering scenarios. It does not discuss side effects like overwriting (though an 'overwrite' parameter exists), but the key behavioral traits are covered.

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 three concise sentences, each adding distinct value: purpose, default behavior/guidance, and a key requirement. It is front-loaded with the action and avoids filler or repetition. No word 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?

Despite having an output schema, the tool is complex (11 parameters, mutating operation, TMDL writing). The description covers the default cardinality and cross-filtering warning, plus the closed-project prerequisite, but leaves most parameters unexplained and does not describe return values or error scenarios. Given the zero schema coverage, this is not complete enough for an agent to confidently invoke the tool with correct parameters.

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

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

Schema description coverage is 0% for all 11 parameters. The description only adds semantics for 'cross_filtering' (explains the default 'oneDirection' and warns about 'bothDirections') and implicitly for cardinalities (default many-to-one). It does not explain 'from_table', 'to_column', 'is_active', 'overwrite', 'name', 'request_id', or other parameters. This is insufficient for a tool with 11 parameters and zero schema-level documentation.

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

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

The description clearly states the tool's action: 'Crea una relacion entre dos columnas del modelo .pbip' (creates a relationship between two columns). This specific verb+resource combination distinguishes it from siblings like pbi_set_relationship_direction (which changes direction) and pbi_list_relationships (which lists relationships). The scope (.pbip model) is also explicit.

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

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

The description provides explicit guidance on default cardinality and filtering ('muchos-a-uno con filtro en un sentido... lo unico que no introduce ambiguedad') and warns against using 'bothDirections' unless justified. It also states a critical prerequisite: the project must be CLOSED in Power BI Desktop when writing TMDL. However, it does not explicitly name sibling alternatives, so it lacks a direct when-to-use vs. alternative comparison.

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

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

The description discloses significant behavioral details beyond the annotations: validation of roles, rejection of unknown roles and format keys, silent ignoring of unrecognized option keys, backup creation, and template cloning. It also explains how field type constraints are enforced, giving the agent a clear mental model of side effects.

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

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

The description is long but well-organized into sections (visual_type, fields, options, position, behavior). It starts with a clear purpose, front-loads the essential information, and each section adds necessary detail without redundancy. The length is justified by the tool's complexity and the need to disambiguate behaviors.

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

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

Given the tool has 7 parameters, nested objects, and an output schema, the description covers parameter semantics, validation rules, side effects (backup), and references related tools. It is complete enough for an agent to select and invoke the tool correctly, even without seeing the output schema.

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

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

Schema description coverage is 0%, and the description completely compensates by explaining every parameter: visual_type enumerate, fields mapping format, options keys per visual type, position structure, and the role of title/request_id. It includes examples and clarifies the difference between ignored and rejected options.

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 'Crea un visual PBIR en una pagina', clearly stating the action and resource. It details the supported visual types and distinguishes itself from related sibling tools by focusing on creation with validation and options.

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 this tool (creating a visual) and references sibling tools like pbi_list_visuals and pbi_get_visual for related tasks. However, it does not explicitly state when to use alternatives such as pbi_duplicate_visual or pbi_delete_visual, so exclusions are 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.

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

The description clearly discloses that the tool writes a file (`pbi-brief.json`) next to the .pbip, outside .Report/.SemanticModel, and that overwriting is normal because dashboards change purpose. It also explains that the agent must not fabricate answers. This adds meaningful behavioral context beyond the sparse annotations and does not contradict 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?

The description is long but purposeful. It front-loads the main verb and resource, uses a bolded warning for the most important behavioral rule, and packs useful details about parameter semantics and file storage. While not as terse as possible, every sentence adds relevant 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?

For a tool that writes a brief file, the description is fairly complete: it explains the file location, why it is stored there, the human-interaction requirement, and key parameters like delivery and critical_fields. The presence of an output schema reduces the need to describe return values. Some parameter descriptions are missing, but the overall context is sufficient for effective use.

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

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

The input schema has 0% description coverage, so the description carries a heavy burden. It does explain `delivery` (with enum values and meaning) and `critical_fields` (structure and purpose), and indirectly covers `purpose` and `audience`. However, several other parameters like `decisions`, `non_goals`, `request_id`, `key_questions`, and `update_cadence` are not described, leaving gaps.

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

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

The description opens with a specific verb and resource: 'Escribe el BRIEF DE INTENCION del tablero' (Write the intent brief of the dashboard). It clearly defines the artifact's role as governing other pieces and distinguishes it from sibling tools like pbi_get_brief by focusing on creation and intent capture rather than retrieval.

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 strong usage guidance: it explicitly says to ask the human before calling, lists specific questions to ask, and warns that an agent-invented brief is worse than none. It does not explicitly name alternative tools, but effectively communicates when not to use it by emphasizing that answers must come from the human.

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

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

Annotations only provide negative hints (readOnlyHint=false, etc.), placing the burden on the description. The description does add context about the contract structure, the mandatory shared key, and its role in validation. However, it does not disclose whether writing overwrites an existing file, what side effects occur (e.g., creating/updating the file), or any permission requirements. This is moderate transparency—useful context but not full behavioral 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 moderately lengthy but each sentence serves a purpose: it states the action, corrects a common misconception, gives the dataset schema, explains the key's importance, and notes the validation workflow. It is well-structured and front-loads the main verb. It could be slightly condensed, but it earns its length by preventing misuse.

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

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

The tool has an output schema (not shown), so return values need no explanation. The description covers the main action, the conceptual background, the dataset shape, and the relationship to validation tools. It does not explain optional parameters (name, request_id) or overwrite behavior, but for a definition/write tool with a well-defined primary parameter, 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?

With schema description coverage at 0%, the description must compensate. It does so for the main `datasets` parameter by providing a detailed inner structure: [{name, key, columns: [{name, type, required?}], emitted_by?, description?}], and explicitly states the `key` is mandatory. However, it does not explain the `name` and `request_id` parameters, leaving some semantic gaps. This is strong compensation for the primary param but incomplete for all params.

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 "Escribe el CONTRATO del puerto del ecosistema (pbi-port-contract.json)" — a specific verb (write) and resource (the port contract file). It distinguishes the tool from pbi_check_contract (which validates) and pbi_define_brief (which defines the brief), and clarifies the port is a data contract, not an API bus. This makes the tool's purpose unambiguous.

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

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

The description explains the contract 'vive versionado junto al .pbip' and that it is validated with pbi_check_contract, giving clear context for when to use this tool (to define/write the contract) versus when to use the validation sibling. It also explains the rationale for the contract approach. However, it lacks explicit 'when not to use' or alternative tool exclusions, so it stops 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?

Beyond the annotations that declare destructiveHint=true, the description adds the crucial requirement 'confirm=true' to actually execute the deletion. It also mentions the side effect of removing the bookmark from the index, providing useful behavioral context beyond the structured metadata.

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 short sentences, front-loads the verb and resource, and wastes no words. It efficiently conveys the action, the index side effect, and the destructive confirmation requirement.

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 delete operation with an output schema and annotations, the description is mostly complete. It warns about destructiveness and the confirm flag, but does not mention failure scenarios (e.g., bookmark not found) or what happens if confirm is false. Acceptable for simple 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It explains that 'confirm' must be true for deletion, and 'name' is implicitly the bookmark to delete, but 'request_id' remains undocumented. Partial compensation, but not complete.

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 'Borra un marcador' (deletes a bookmark) and specifies the additional behavior 'lo quita del indice' (removes it from the index). This distinguishes it from sibling tools like pbi_create_bookmark or pbi_list_bookmarks.

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 (when you want to delete a bookmark) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The destructive warning hints at caution but does not elaborate on when to avoid use.

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

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds significant behavioral context: it explicitly warns that the operation is destructive and requires confirm=true, clarifies that 'live' needs Desktop open while 'pbip' needs it closed, and explains the 'auto' fallback logic. This provides valuable operational detail not inferable from the annotations alone.

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 paragraph that front-loads the primary purpose and then explains mode behavior. It contains no filler, but the mode explanation is slightly verbose and could be tightened. It is reasonably concise and well-structured for the complexity involved.

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

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

The description covers the key aspects needed to use the tool safely: destructive nature, confirm requirement, mode selection with prerequisites, and default behavior. With an output schema present to describe return values, the description is sufficiently complete. Minor gaps like error handling or missing-measure behavior are not critical.

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

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

With 0% schema description coverage, the description compensates by explaining the 'mode' and 'confirm' parameters in detail, including the disabled 'both' option and the default behavior. The 'table' and 'name' parameters are not described, but their names are self-explanatory. 'request_id' is not explained, but it is a common internal field. The description adds enough value over the schema to earn a 4.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Elimina una medida' (Deletes a measure). This distinguishes it from sibling tools like pbi_create_measure, pbi_update_measure, and pbi_rename_measure, which handle other operations on measures.

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

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

The description provides explicit guidance on when to use different values of the 'mode' parameter (live, pbip, auto), including the note that 'mode=both' is temporarily disabled and the default 'live' requires Power BI Desktop open. It also advises using 'auto' or 'pbip' when building from scratch. However, it does not mention alternatives like 'update measure' or when not to use this tool, so it falls 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?

Annotations already declare destructiveHint=true, but the description adds valuable context beyond that: confirm=true is mandatory, the tool refuses to delete the last page (with a rationale), and it updates page order and active page. No contradiction with annotations.

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

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

The description is extremely concise: two sentences that front-load the core action and then provide essential safety caveats. Every sentence adds value, with no redundant wording.

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 the presence of an output schema, the description covers all critical operational aspects: destructive nature, confirmation requirement, and the last-page guard. The agent has enough information to invoke the tool correctly without needing additional details.

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

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

The schema has 0% description coverage, so the description must compensate. It does clarify that confirm must be true and implies page is the target. However, it does not explain the format of 'page' or the purpose of 'request_id', leaving some parameter ambiguity.

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 ('Elimina una pagina') and resource ('pagina'), clearly identifying the delete action. It also mentions side effects (updating order and active page), which distinguishes it from sibling tools like pbi_duplicate_page, pbi_rename_page, and pbi_reorder_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 explicitly states that the tool is destructive and requires confirm=true, and it warns against deleting the last page. This provides clear usage guidance, though it does not name alternative tools. However, the deletion action is unique among siblings, so the guidance is sufficient.

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

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

The description goes beyond the destructiveHint annotation by disclosing the confirm=true requirement, the return of the previous definition, and the journal-based restore capability. These are meaningful behavioral details that help the agent understand the tool's safety and recovery mechanisms. No contradiction with annotations.

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

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

The description is extremely concise, two sentences long, with the core action first and important constraints immediately following. Every sentence earns its place with no redundant information.

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

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

Given the destructive nature, the description adequately covers the key context: what it does, the confirmation requirement, and the recovery path via journal. The presence of an output schema likely covers return value details, and annotations cover destructiveness. It could mention error conditions, but the current level is sufficient for a delete 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?

With 0% schema description coverage, the description must compensate. It explicitly explains the confirm parameter ('requiere confirm=true') but does not elaborate on page, visual_id, or request_id. The parameter names are relatively self-explanatory, but the description only partially covers the parameter semantics.

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 'Elimina un visual' clearly states the action (delete) and resource (visual), distinguishing it from sibling tools like pbi_delete_bookmark and pbi_delete_page. It also adds important context about destructiveness and confirmation, making the purpose unambiguous.

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

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

The description implies usage by framing it as a destructive operation that requires confirm=true, which signals when to use it (intentional deletion with confirmation) and cautions against careless use. It does not explicitly name alternatives or exclusion scenarios, but the context is sufficient.

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

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

The description adds behavior beyond the read-only annotation by listing concrete issue categories and noting that 'Cada hallazgo trae su evidencia geometrica' (each finding includes geometric evidence). It also repeats the read-only hint but does not contradict annotations.

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

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

The description is front-loaded with the core purpose in the first line, followed by a concise bullet-like list of detections and a one-line note about evidence. Every sentence earns its place 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?

Given the tool's single optional parameter, output schema, and read-only annotation, the description is complete: it states scope (one/all pages), what issues are found, and that findings include geometric evidence. No critical information 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 0% schema coverage, the description fully compensates by explaining that the page parameter targets one page or all pages ('de una pagina (o de todas)'). The default null meaning is clear: omitting the parameter diagnoses all pages. This directly clarifies the only 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 a specific verb+resource: 'Diagnostica la geometria de una pagina' and enumerates exact layout issues detected (overlaps, off-canvas visuals, small sizes, margins, inconsistent spacing, Z-order problems, empty/saturated pages). This clearly differentiates it from sibling audit or documentation tools.

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

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

The phrase 'Diagnostica la geometria de una pagina (o de todas)' provides clear context for when to use this tool: to diagnose layout geometry on one or all pages. It does not explicitly state exclusions or name alternatives, so it misses the top score.

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

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

The description goes well beyond the annotations by explaining deterministic behavior, absence of heuristics, how skipped checks are reported, severity assignment for critical fields, and the requirement for a live open model. This adds substantial context not available from the readOnlyHint and openWorldHint annotations.

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

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

The description is dense yet well-structured, starting with a clear purpose statement followed by a bulleted list of checks, then behavioral notes and prerequisites. Every sentence contributes value, with no redundant or filler content, and the front-loaded opening ensures quick comprehension.

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 (four checks, skipped states, severity rules, prerequisites), the description is remarkably complete. It explains what each check does, how failures are categorized, the deterministic vs. subjective split, the skipped status semantics, and the model-open requirement. The output schema exists, so return values need not be described.

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

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

The schema provides no descriptions for the two parameters (0% coverage), so the description must compensate. It explains the `tables` parameter's filtering semantics effectively ('narrows to relationships that touch those tables'), but it does not mention `request_id` at all. Thus, the compensation is partial, leaving one parameter completely unexplained.

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 ('diagnose') and resource (data content against the live model), and enumerates the four deterministic checks. It distinguishes itself from metadata-only audit tools by explicitly targeting what 'breaks dashboards and no metadata sees', making it unique among 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 provides clear context for when to use this tool: to find data-level issues invisible to metadata, and it notes the prerequisite of an open model in Desktop. However, it does not explicitly contrast with alternatives like pbi_profile_data or pbi_analyze_model_quality, nor does it state when not to use it, stopping short of the 'explicit alternatives' benchmark.

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?

Given readOnlyHint: true, the description adds value by specifying the concrete behavioral outputs (added, leftover, same visuals) and how missing pages are handled (reports that it will be created). This exceeds the annotation baseline without contradicting it.

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