Power BI Report MCP Server

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

The description reveals a key behavioral detail: the bookmark is created with an empty exploration state, requiring manual capture in Power BI Desktop. This adds value beyond the annotations (which only have openWorldHint=false). For a creation tool, it offers reasonable 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 exceptionally concise: two sentences with no unnecessary words. The purpose is stated first, followed by a key behavioral note. It is well-structured and efficient.

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

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

Given the tool's simplicity (create bookmark with two parameters) and no output schema, the description covers the core functionality and important caveat (empty state). It could mention the required report context but overall is adequate.

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

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

Schema description coverage is 100%, so the parameters are already well-documented in the schema. The description does not add any additional meaning or context about the parameters (displayName and activePageId), so it meets the baseline but does not exceed it.

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: 'Create a new bookmark.' It also adds context that the bookmark starts empty, which distinguishes it from other bookmark operations like renaming or deleting.

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 hints at usage by advising to use Power BI Desktop to capture the view state, but it does not explicitly state when to use this tool versus alternatives like pbir_list_bookmarks or pbir_rename_bookmark. No exclusion criteria or comparison to siblings is 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 are minimal (only openWorldHint=false), so the description carries the burden. It explains filter types and compound operators, adding context beyond the schema. However, it does not disclose side effects, permissions, error behavior, or what happens on duplicate filters.

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

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

The description is extremely concise with two sentences, no redundant information, and front-loads the main action. Every sentence adds essential guidance.

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 (19 parameters, multiple filter types), the description covers key patterns and constraints. No output schema exists, but the tool's purpose is straightforward. It does not explain return values, but that is acceptable for an add 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 description coverage is 58%, and the description adds value by grouping parameters under filter types and explaining compound operators. However, many parameters (e.g., n, count, value) still rely on brief schema descriptions, and the description does not fully detail all parameter semantics for each filter type.

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

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

The description clearly states 'Add a filter to a page or visual', using a specific verb and resource. It distinguishes between page-level and visual-level filters by mentioning omitting visualId, and lists filter types, making it unambiguous.

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

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

The description provides clear guidance on when to use which parameters (e.g., 'Omit visualId for page-level', 'topN requires visualId', and lists filter types with operator details). However, it does not explicitly compare to sibling tools like pbir_remove_filter, though the name implies addition.

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 (only `openWorldHint: false`), so the description carries the burden of behavioral disclosure. It mentions batch addition and inline formatting but does not explain key behaviors such as whether visuals are appended or replaced, idempotency, permissions, or error handling. The potential for destructive actions is not addressed.

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 concise: four sentences with no wasted words. The first sentence front-loads the core action, followed by key features and specific examples. Every sentence adds value.

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

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

Given the tool's complexity and the lack of an output schema, the description is adequate but incomplete. It covers main use cases but omits return value information (e.g., what IDs are returned) and behavioral details like duplicate handling or error conditions. The tool has many adjacent siblings, but the description does not fully differentiate them.

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 80%, so the schema already documents most parameters. The description adds value by explaining visual-type-specific bucket names (Series, Category) and directing users to `pbir_lookup_theme_property` for valid names. This semantic enrichment goes beyond the schema.

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

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

The description clearly states the tool adds visuals to a page in batch via the `visuals` array. It distinguishes from sibling tools like `pbir_format_visual` by noting that inline formatting avoids extra calls. Specific visual types (stacked charts, KPI card, scatter) are mentioned, making the purpose precise.

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

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

The description provides guidance on when to use this tool (batch add with inline formatting to avoid extra calls) and gives specific usage tips for different visual types (e.g., 'Stacked charts need a Series binding'). It also recommends using `pbir_lookup_theme_property` for valid names. However, it does not explicitly exclude 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?

With only openWorldHint: false in annotations, the description adds value by specifying scope (all visuals on a page) and listing available themes. However, it does not disclose behavioral traits like overwrite behavior, undoability, or side effects, which would be expected 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 with no redundancy. The first sentence clearly states purpose, the second lists themes. Every word earns its place, making it easy to parse quickly.

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

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

Given the lack of output schema and minimal annotations, the description should cover more aspects like what happens to existing formatting, how applyDataColors behaves, or prerequisites. It feels incomplete for a tool with three parameters and no return type.

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 only 33% (pageId has description). The description adds no further meaning for pageId or applyDataColors beyond the schema, and only repeats enum values for theme which is already defined. Since coverage is low, the description should compensate but does not.

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

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

The description clearly states the action (apply a named theme preset) and the scope (all visuals on a page), with an explicit list of theme options. This distinguishes it from sibling tools like pbir_set_report_theme which likely operate at the report level.

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

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

No guidance is provided on when to use this tool vs alternatives such as pbir_set_report_theme or pbir_lookup_theme_property. The description lacks context for selection, and there are no when-to-use or when-not-to-use indications.

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 behavioral context beyond annotations: it specifies the output format (summary header + topN findings) and the behavior of the topN parameter (0 = all). No contradiction with annotations (readOnlyHint true).

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 efficiently convey purpose and key parameter behavior. Zero wasted words.

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

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

Given the presence of an output schema and comprehensive parameter descriptions in the schema, the description covers the essential aspects. Minor gap: does not mention that the audit is per page or that it requires a pageId, but that is clear from the schema.

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

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

Schema coverage is 100%, so the description's extra detail on topN (default 20, 0 = all) adds marginal value. It does not explain the verbose parameter beyond the schema.

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

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

The description clearly states the action ('Audit'), the resource ('visuals on a page'), and the specific aspect ('theme overrides'). It distinguishes itself from sibling tools that handle other operations like setting visibility or applying themes.

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 checking theme compliance on a page, but does not explicitly mention when to use this tool versus alternatives. However, given the readOnlyHint annotation, it is safe to use without side effects.

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 and annotations provide minimal behavioral details. No indication of how the grid is computed, whether existing positions are overridden, or what the output is. Annotations only have 'openWorldHint: false', which does not add behavior context.

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

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

The description is overly brief (one sentence) and under-specified. While concise, it sacrifices necessary detail, making it less helpful. A short description should still capture key behavioral aspects.

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 incomplete given the tool's complexity and lack of output schema. It does not explain behavior like whether it affects all visuals or only those on the specified page, what the grid layout algorithm does, or what happens to existing margins. The sibling list shows many layout tools, but this one is not contextualized.

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 low (20%): only 'pageId' has a description. The tool description adds no parameter meaning beyond listing defaults. 'columns', 'padding', 'marginTop', 'marginLeft' are 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 the tool's purpose: 'Auto-arrange all visuals on a page in a grid.' It uses a specific verb (arrange) and resource (visuals on a page), but does not differentiate from the similar sibling 'pbir_layout_grid'.

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

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

No guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or excluded conditions. The one-sentence description provides no usage 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?

Discloses that bindings are replaced and that continueOnError validates per-entry, adding value beyond the sparse annotations. No contradiction.

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

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

Two sentences with front-loaded purpose; each sentence adds essential guidance 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?

Covers main usage and key parameters, but lacks information about return values or error handling, which 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?

Adds contextual guidance beyond the schema's parameter descriptions (e.g., when confirmBulk is required), though schema coverage is already high.

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

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

States 'Rebind multiple visuals in one call' with specific verb and resource, and distinguishes from sibling tool for single visual updates.

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 context for when to use (bulk operation) and explicit guidance on confirmBulk and continueOnError, but does not explicitly exclude single visual case.

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 mark the tool as destructive (destructiveHint=true). The description adds the condition for the confirmBulk parameter, which is a safety behavior. However, it does not disclose error handling or side effects when the condition is not met. The additional behavioral context is useful but not extensive.

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, no filler. Purpose is front-loaded, and the critical parameter guidance is included. Every word earns its place.

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

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

The description covers the main action and key parameter constraint. However, it omits details like return value, error conditions, and the fact that pageId auto-resolves (though in schema). For a destructive bulk operation, more context (e.g., irreversibility) would improve completeness, but the essential info is present.

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 67%: pageId and confirmBulk have descriptions, visualIds lacks one. The tool description repeats the confirmBulk condition but does not clarify visualIds (e.g., format, source). It adds minimal value beyond the schema.

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

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

The title and description clearly state 'Delete multiple visuals from a page,' which is a specific verb and resource. It is distinct from the sibling tool pbir_delete_visual, 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 provides guidance on when to set confirmBulk (when >5), but does not explain when to choose this tool over alternatives like pbir_delete_visual or pbir_bulk_delete_visuals (though the name implies bulk use). No explicit when-not-to-use or alternative differentiation is given.

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

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

Annotations only include openWorldHint:false, but the description does not disclose potential side effects, reversibility, or error behavior (e.g., what happens if confirmBulk is false and count >5). The confirmBulk hint is more a usage guideline than behavioral transparency.

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

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

The description is extremely concise (two sentences) with no wasted words. The first sentence states the core purpose, and the second adds essential parameter guidance. Front-loaded and effective.

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 5 parameters, 2 required, no output schema, and low schema coverage, the description covers key aspects: purpose, target modes, and confirmBulk requirement. It does not mention return values or error handling, but the schema covers the formatting structure. In context of sibling tools, it is reasonably complete.

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

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

Schema description coverage is 40% (descriptions for pageId, target, confirmBulk). The description adds semantics for target (container vs visual modes) and confirmBulk usage. However, it does not elaborate on visualIds or the formatting array structure beyond what the schema provides.

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 'Apply the same formatting to multiple visuals' and explains the two target modes (container for title/background/border, visual for axes/legend/labels), distinguishing it from sibling tools like pbir_format_visual which format a single visual.

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

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

The description provides clear guidance on when to use each target type and requires confirmBulk:true when applying to more than 5 visuals. It does not explicitly exclude alternative tools or scenarios, but the sibling list implies pbir_format_visual for single visuals.

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

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

The description reveals the primary behavior (changing visual type) and that data bindings are preserved, but does not disclose potential constraints (e.g., visual must exist, compatibility of visual types). Annotations provide no additional safety hints, so the description carries the burden; it is adequate but could be improved.

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

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

The description is a single clear sentence that immediately communicates the action and key feature (keeping data bindings). Every word is purposeful; there is no wasted 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?

Given the tool has only three required parameters, no output schema, and no nested objects, the description is fully sufficient. It covers the core function and the constraint, which is all that is needed for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds an example but does not provide additional meaning beyond the schema's built-in descriptions for the three parameters.

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

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

The description clearly states the action (change visual type), the resource (existing visual), and the key constraint (keeping data bindings). The example further clarifies the input format. This distinguishes it from sibling tools like pbir_add_visual or pbir_format_visual.

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

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

The description implies when to use by stating 'while keeping data bindings', but does not explicitly define when not to use or mention alternatives. Since the tool is unique among siblings, a score of 4 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 already mark destructiveHint=true. The description adds the specific scope (page or visual) and the all-encompassing nature of the removal, providing moderate additional context 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?

Single, concise sentence that immediately conveys the core action. No redundancy or filler; each word earns its place.

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

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

For a simple destructive action with no output schema, the description adequately covers the tool's behavior. Minor omission: no mention of behavior when no filters exist or return value, but overall sufficient for correct usage.

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 100%, with both parameters already described in the schema. The description reiterates the same information without adding new meaning, earning baseline 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 ('Remove ALL filters') and the resource scope ('from a page or a specific visual'). It effectively distinguishes from sibling tools like pbir_remove_filter by emphasizing 'ALL' filters.

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

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

No explicit guidance on when to use this tool versus alternatives like pbir_remove_filter. The description only explains what it does, without providing context for selection.

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

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

The description states it creates a page, clearly a mutation, but provides no additional behavioral context such as side effects, permissions, or limits (e.g., maximum pages, does it set active page). The description adds the three types, which is helpful, but overall it's minimal for a creation operation with no annotations about destructive 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 a single concise sentence, front-loaded with the action and key information. No unnecessary words. Could potentially add more detail without being verbose, but it is efficient as is.

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

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

Given 6 parameters, 1 required, and nested objects, the description is relatively brief. It does not mention the return value (no output schema), position of new page, activation behavior, or constraints like unique display name. However, the schema covers parameter descriptions comprehensively, so the description is minimally adequate.

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

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

Schema has 100% description coverage, so the description's role is reduced. The description mentions 'standard, tooltip, and drillthrough page types', but the schema already describes the 'type' parameter and the 'drillthrough' object. The description does not add significant new meaning beyond what is in the schema.

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

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

Clearly states 'Create a new page' and lists the supported types (standard, tooltip, drillthrough). This distinguishes it from other page manipulation tools like rename or delete. However, the phrase 'drillthrough page types' could be misinterpreted because drillthrough is not an enum value for the 'type' parameter but a separate property.

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

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

No explicit when-to-use or when-not-to-use guidance. The description implies it is for creating pages of various types, but doesn't compare to alternatives like pbir_duplicate_page. The usage context is left 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?

The annotations already indicate destructiveHint=true, so the description does not need to restate that. However, it adds no extra behavioral context beyond the basic action, like irreversibility or permission requirements.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core purpose with zero wasted words.

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

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

For a simple delete operation with no output schema, the description is sufficient. It identifies the required input and the action. Minor gaps like side effects do not significantly 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?

Schema description coverage is 100%, with the parameter already described as 'The bookmark ID to delete (from pbir_list_bookmarks)'. The tool description adds no additional semantic value beyond what the schema provides.

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

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

The description clearly states the action ('Delete') and the resource ('a bookmark') with the method ('by ID'). It uniquely identifies the operation among sibling tools like pbir_add_bookmark and pbir_rename_bookmark.

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 specifying the input (bookmark ID from pbir_list_bookmarks), but provides no explicit guidance on when to use this tool versus alternatives, such as renaming or listing bookmarks.

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 destructive behavior (destructiveHint: true). The description adds the important detail that all visuals on the page are also deleted, which provides useful behavioral context 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 a single, efficient sentence that conveys the essential action. It is front-loaded and wastes no words, though it could be slightly more informative without losing brevity.

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

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

For a simple destructive operation with one parameter and no output schema, the description covers the basic functionality. However, it lacks completeness regarding edge cases, such as effects on related bookmarks or filters, and does not mention any constraints.

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 100% and the single parameter 'pageId' is described as 'The page ID to delete' in the schema. The tool description adds no additional semantic information beyond what the schema already provides, so baseline 3 is appropriate.

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 deletes a page and its visuals, with a specific verb and resource that distinguishes it from sibling tools like pbir_duplicate_page or pbir_set_page_visibility.

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

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

No guidance is provided on when to use this tool versus alternatives, e.g., whether deleting the active page is allowed or if there are prerequisites like no active visuals. The description lacks context for 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?

The annotations include destructiveHint=true, so the agent knows it's destructive. The description adds no further behavioral context (e.g., no mention of success state, error handling, or undo capability), but annotations already convey the key trait.

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, front-loaded sentence with no wasted words. It conveys the essential purpose efficiently.

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 one required parameter and a destructive annotation, the description is mostly adequate. However, it lacks mention of error conditions or return behavior (no output schema), and does not explicitly state irreversibility beyond the annotation.

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 100%, so the schema fully defines parameters. The description adds no additional meaning beyond what the schema provides, such as clarifying the auto-resolution of pageId or the format of visualId.

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 'Delete a visual from a page' clearly states the action (delete) and the resource (visual from a page), distinguishing it from siblings like pbir_bulk_delete_visuals (bulk delete) and pbir_delete_bookmark (delete bookmark).

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 (e.g., pbir_bulk_delete_visuals for multiple visuals), no prerequisites, and no mention of irreversibility beyond the annotation.

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, and the description reinforces this by stating it returns a diff without side effects. It adds value by explaining the output structure (added, removed, changed) beyond what annotations provide.

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

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

The description is two concise sentences that front-load the action and output, wasting no words.

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

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

Given the tool has an output schema (implied), the description adequately conveys the input and output semantics. The sibling tools provide context for usage, and no additional details are needed.

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

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

Schema coverage is 100% for the single parameter 'theme'. The description explains the parameter's purpose in context (comparing against current theme and producing a diff), which adds meaning beyond the schema's description.

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

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

Description clearly states the tool compares a proposed theme JSON against the current theme and returns additions, removals, and changes. It distinguishes itself from sibling tools like pbir_apply_theme by emphasizing previewing before applying.

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 notes the tool is 'useful for previewing theme changes before applying,' giving clear context for when to use it. However, it does not explicitly mention when not to use it or list alternatives like pbir_apply_theme.

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?

Minimal disclosure beyond annotations. The annotation only provides openWorldHint=false, and the description adds no behavioral details such as side effects, placement of the new page, or whether filters/bookmarks are copied.

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?

Single sentence, concise and front-loaded with the key action and resource. 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?

Adequate for a simple tool with no output schema, but lacks details on new page positioning, default order, and what aspects of the original page are duplicated (e.g., filters, bookmarks).

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 100% schema description coverage, the schema already documents both parameters. The description adds no additional meaning beyond what is in the schema, resulting in baseline 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 ('duplicate an entire page with all its visuals') and the resource ('a new page'), distinguishing it from sibling tools like pbir_create_page (create blank page) and pbir_delete_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 implies when to use this tool (copying a full page) but provides no explicit when-to-use or when-not-to-use guidance, nor compares it to alternatives like pbir_create_page or pbir_duplicate_visual.

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 only states the basic operation. It does not disclose side effects, whether the duplication is deep or shallow, or any permissions required. Annotations are minimal (openWorldHint: false), so the description carries the burden, but fails to provide sufficient behavioral context.

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

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

The description is a single, front-loaded sentence that conveys the essential information without any unnecessary words. Every part contributes to understanding the tool's purpose.

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

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

Given the tool's complexity (5 parameters, no output schema) and the minimal description, there is a lack of completeness. The description does not explain default behavior, return values, or constraints like coordinate systems, which are important for correct invocation.

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

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

Schema coverage is 100%, with each parameter described. The description adds no additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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 (duplicate) and resource (visual), with added specificity about optional repositioning and cross-page duplication. This distinguishes it from sibling tools like pbir_duplicate_page or pbir_move_visual.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives (e.g., move_visual or add_visual). The usage context is implied by the action, but no exclusions or prerequisites are mentioned.

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

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

Discloses auto-routing logic and gotchas, which adds behavioral context beyond annotations. However, it does not explicitly state nondestructive nature or permissions, though inferences are clear.

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 front-load the purpose and routing logic, then add important gotchas. No wasted words; each sentence is 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 the tool's complexity (routing, gotchas), the description covers all key usage aspects: routing behavior, override mechanism, reference to lookup tool, and visual-specific caveats. Output schema is absent but not required.

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 100% schema coverage, the description adds significant value by explaining routing details, override options, and specific property examples, exceeding the baseline of 3.

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

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

The description clearly states it formats visual properties, with specific auto-routing behavior and override options. It distinguishes itself from sibling tools like pbir_set_visual_title and pbir_bulk_update_format.

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

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

Provides explicit guidance on when to use auto-routing vs overrides, references pbir_lookup_theme_property for valid names, and highlights important gotchas for slicer and waterfall visuals.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't repeat that. It adds transparency by revealing the tool returns a boolean indicating the existence of a `.SemanticModel/` folder, which is useful behavioral context. A slightly richer output description could improve, but it's already good.

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 only two sentences, front-loading the purpose, then providing an output detail and a usage hint. Every sentence adds value 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?

Given no parameters, an existing output schema (per context), and annotations covering read-only, the description adds critical context about the `hasSemanticModel` flag and its relation to a sibling tool, making the tool fully self-explanatory for an agent.

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

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

There are no parameters, so schema coverage is trivially 100%. The description has no parameter info to add, and per rubric, 0 parameters with full coverage warrants a baseline of 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 shows the currently connected report path and includes the `hasSemanticModel` boolean. This distinguishes it from sibling tools which manipulate visuals, pages, or other aspects.

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

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

The description explicitly advises to check `hasSemanticModel` before calling `pbir_model_usage`, providing a concrete when-to-use and when-not-to-use guideline. This is direct and unambiguous.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it is a safe read operation. The description adds no further behavioral context (e.g., what happens to the report state, whether any side effects exist). With annotations covering safety, the description is adequate but not enriching.

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 short sentence that is front-loaded and contains no unnecessary words. It efficiently conveys the tool's purpose.

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

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

The tool has no output schema and no parameters. The description is minimal: it states what is retrieved but does not explain the return format or any nuances (e.g., whether settings and theme are returned together or separately). Given the lack of output schema, the description should provide more detail for 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?

There are no parameters, so schema coverage is 100% trivially. The description does not need to explain parameters. Baseline score of 4 applies as no parameter information is needed.

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

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

The description clearly states the verb 'Get' and the resource 'report-level settings and theme configuration', which distinguishes it from siblings like pbir_get_report_theme (which gets only theme) and pbir_update_report_settings (which updates settings).

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., pbir_get_report_theme for theme-only retrieval). The context of siblings implies differentiation but the description does not provide explicit when-to-use or when-not-to-use advice.

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, and description adds value by specifying the return format (base theme name + custom theme JSON), going 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?

Single sentence with no wasted words, front-loaded with the key action and output description.

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

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

For a simple getter with no parameters and an output schema present, the description is fully adequate—covering purpose, output, and conditions.

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

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

No parameters exist, so schema coverage is 100%. Baseline score of 4 applies as per guidelines for 0-parameter tools.

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

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

Description clearly states 'Get the currently applied theme' with specific verb and resource, and distinguishes from sibling tools like pbir_apply_theme and pbir_set_report_theme which are write operations.

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

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

The description implies usage for reading the current theme, but lacks explicit when-not-to-use or alternatives. The context from sibling names provides differentiation.

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 mark readOnlyHint=true. The description adds valuable behavioral context: default returns a summary, verbose returns full raw PBIR JSON. No contradictions.

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

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

Two concise sentences, front-loaded with purpose, minimal waste. Every sentence adds value.

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

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

Given the output schema exists, the description adequately covers default and verbose output. No missing information for a read tool with rich schema and annotations.

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 100%, so baseline 3. The description adds meaning by stating 'slim' is deprecated alias for '!verbose', and explains verbose effect beyond schema. Provides useful nuance.

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 'Get visual details' clearly states the action and resource, with specific details on default output and the verbose option, distinguishing it from listing or mutation 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?

No explicit guidance on when to use this tool versus alternatives like pbir_list_visuals for listing all visuals or other getters. The context implies it's for reading a single visual, but lacks explicit when-not or alternative references.

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 mark it as read-only. The description adds valuable behavioral details: default returns a slim list (~150 tokens), verbose returns detailed metadata (~1,200 tokens). No contradictions.

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

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

Two sentences, no fluff. The main purpose is front-loaded, and each sentence adds distinct value.

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

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

For a simple read-only list tool with one optional boolean parameter and no output schema, the description fully explains the behavior and output variants.

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 covers the verbose parameter's description, but the description adds meaning by specifying default vs verbose output formats and token sizes, aiding the agent in deciding which mode to 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 states 'List available visual types' which is a clear verb+resource. It distinguishes from siblings like pbir_list_visuals (which lists visuals in a report) by focusing on types, not instances.

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

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

The description explains when to use the default vs verbose mode, providing context on token consumption. However, it does not explicitly state when to choose this tool over alternatives, though it's the only tool for listing visual types.

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

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

Annotations already indicate readOnlyHint=true. The description adds transparency about live discovery from skills/*.md files, informing the agent that topics are dynamically sourced. No destructive behavior is implied, and there is no contradiction with annotations.

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

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

The description is extremely concise: two sentences that front-load the purpose and immediately provide actionable usage. Every sentence earns its place without redundancy.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers the essential aspects: domain, live discovery, and listing capability. It is complete enough for the agent to understand how to invoke it, though it could optionally mention the expected response format.

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 already describes the 'topic' parameter with a description. The tool description adds the crucial usage example of passing 'list' to enumerate topics, which goes beyond the schema's definition and enhances 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 defines the tool as providing domain knowledge for Power BI report development, with a specific mention of live discovery from skills/*.md files. This distinguishes it from sibling tools which focus on specific actions like setting page visibility or renaming 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 provides explicit guidance on how to list available topics using topic:'list', which aids in initial discovery. However, it does not explicitly state when not to use this tool, relying on contrasting sibling tool purposes.

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 behavioral details beyond the sparse annotations: server handles margin/gap math, planOnly mode behavior, and reserveBannerRow effect. No contradictions.

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

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

Two sentences with zero waste. Front-loaded with purpose, followed by usage guidance and key behavioral 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?

Given the complexity (11 params, nested objects, no output schema), the description covers core behavior and usage. However, it lacks details about the return format of the plan, which is a minor 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?

Schema coverage is 82%, so most parameters are documented. The description adds value by summarizing planOnly behavior and referencing guide('wireframes'), though it doesn't explain each parameter individually.

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

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

The description clearly states the tool computes a deterministic grid and positions cells, and distinguishes it from N pbir_add_visual calls. It also explains the planOnly mode.

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 'Use this INSTEAD of N pbir_add_visual calls when building a page from scratch.' It also differentiates when to use planOnly:true vs false, providing clear context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows it's a read-only operation. The description adds no further behavioral details beyond what annotations and output schema provide, which is adequate but not exemplary.

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, short sentence that efficiently conveys the purpose. It is well-structured and front-loaded, but could potentially add a note about the output without losing conciseness.

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

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

Given the tool's simplicity, zero parameters, presence of annotations, and an output schema, the description provides complete contextual information. No missing elements are apparent.

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 description correctly omits parameter details. The schema coverage is 100%, and the description does not need to compensate for missing parameter info. Baseline 4 applies.

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 lists all bookmarks in the report, using a specific verb and resource. It distinguishes itself from sibling tools that add, rename, or delete 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?

No guidance is provided on when to use this tool versus alternatives like pbir_add_bookmark or pbir_delete_bookmark. There is no mention of the context (e.g., enumerating bookmarks before modification) or any prerequisites.

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. The description adds the behavioral detail that slim mode returns Table[Column] strings, which is helpful. No contradictions with annotations.

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

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

The description is extremely concise at two sentences, with no unnecessary words. It front-loads the main purpose and then adds key detail about slim mode.

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

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

Given the presence of an output schema, the description does not need to explain return values. It covers the purpose and slim mode behavior. However, it could briefly mention what happens when pageId/visualId are omitted or error cases.

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 high (67%), but the description adds value for the `slim` parameter which is undocumented in the schema. It explains the default behavior and output format, compensating for the 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 lists filters on a page or visual, distinguishing itself from sibling filter tools like pbir_add_page_filter. It specifies the slim mode output format, making the purpose very clear.

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

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

The description does not explicitly state when to use this tool versus alternatives, or when to use slim vs full mode. It provides implicit context but lacks explicit guidance on usage 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?

Disclosures beyond annotations: totalVisualCount sums full set, slim behavior, and the effect of pageId. No contradictions with readOnlyHint.

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?

Single, well-organized paragraph with no filler. Could benefit from bullet points but remains clear and efficient.

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

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

Covers key behaviors and parameters sufficiently. Output schema exists so return format need not be described. Lacks mention of offset/limit pagination behavior, but parameter constraints are in 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?

Adds context to slim, includeVisuals, and pageId beyond schema descriptions. Explains totalVisualCount and cross-page recommendation. Limit/offset not elaborated but schema provides defaults and limits.

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

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

Clearly states the tool lists pages with pagination. Distinguishes from sibling page tools by specifying functionality and parameter effects.

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

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

Provides guidance on when to use includeVisuals:true vs. per-page calls, and explains totalVisualCount behavior. However, does not explicitly list when to avoid using 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?

Description is consistent with readOnlyHint annotation (listing files). No additional behavioral traits disclosed (e.g., permissions, side effects). The folder path adds minor context but not beyond what annotations already suggest.

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?

Single sentence, no redundancy. Front-loaded with key information. Every word serves a purpose.

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

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

Given zero parameters and a simple list operation, the description fully covers the tool's purpose. Output schema exists to explain return values, so no 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?

No parameters to document. Schema coverage is 100%. Description adds value by specifying the exact folder location for the theme files, which is not in the schema.

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

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

Description clearly states the action (list) and resource (theme files in StaticResources/RegisteredResources/ folder). This distinguishes it from sibling tools like pbir_get_report_theme or pbir_apply_theme.

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

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

No explicit when-to-use or when-not-to-use guidance. However, the name and description imply it's for discovering available theme files, which is distinct from applying or modifying themes. Lacks alternatives context.

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

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

Annotations indicate readOnlyHint=true and openWorldHint=false. The description adds valuable behavioral details: pagination, slim response fields, filterCount inclusion, and auto-resolution of pageId when one page exists. No contradictions.

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

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

The description is appropriately sized with five concise sentences, each adding essential information. The purpose is front-loaded, and every sentence earns its place without redundancy.

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

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

Given the tool's complexity (5 parameters, pagination, filtering), the description fully covers usage scenarios and integration with other tools. The output schema handles return value details, so the description does not need to repeat them.

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 80% schema description coverage, the description adds significant value: it explains slim behavior beyond the schema, reiterates and contextualizes limit/offset, describes pageId auto-resolution, and details visualType filtering before pagination affecting total 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 lists visuals on a page and is paginated. It uses a specific verb-resource combination and distinguishes itself from sibling tools like 'pbir_get_visual' (single visual) and 'pbir_add_visual' by focusing on listing and pagination.

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 pagination with limit/offset, filtering by visualType, and combining with 'pbir_list_pages' for cross-page sweeps. It also explains the slim parameter behavior, offering clear usage context and 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 minimal (openWorldHint false). The description discloses the basic behavior (listing vs activating), but does not detail side effects of activation (e.g., persistence, permission requirements). Adequate but not rich.

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

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

Single, front-loaded sentence with zero wasted words. The two modes are clearly separated in a compact structure.

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

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

Given the simplicity of the tool (one optional parameter, output schema exists), the description is complete. It covers both use cases without needing further elaboration on return values.

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

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

Schema description coverage is 100%, so the schema already documents the parameter. The description clarifies the dual role (list vs activate), adding context beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states two distinct purposes: listing on-demand tools (no arguments) or activating them by name (passing a 'tools' array). This distinguishes it from sibling tools which perform specific report manipulations.

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?

Explains when to use each mode: omit 'tools' to list, provide array to activate. However, no explicit when-not-to-use or alternatives are given, leaving some ambiguity about the scope of 'activate'.

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 behavioral details beyond the readOnlyHint annotation, explaining the progressive query pattern and that propertyFilter is a case-insensitive substring filter. It does not, however, describe error handling or output format (which is covered by the output schema).

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 and highly efficient, using semicolons and plus signs to concisely convey the drill-down pattern. Every part earns its place with no wasted words, making it easy to parse quickly.

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

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

Given that the tool is a simple lookup with optional parameters and an output schema exists, the description completely covers the needed usage context. It explains the progressive query logic, which is sufficient for an agent to use 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?

The input schema already describes each parameter individually (100% coverage). The description adds value by explaining how parameters combine: visualType then category, with propertyFilter as a filter. This hierarchical usage meaningfully extends what the schema provides.

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: to query the Power BI theme schema for valid visualStyles property names. It explains the hierarchical navigation (visual types → categories → properties), which distinguishes it from sibling tools that perform actions like applying themes or modifying visuals.

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

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

The description implies usage by showing the drill-down pattern: no arguments lists visual types, adding visualType lists categories, etc. It provides clear context on how to use the tool but does not explicitly state when not to use it or mention alternatives, though no direct siblings compete.

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 destructive behavior (destructiveHint: true). The description adds critical context: 'Empty file crashes PBI Desktop — tool auto-deletes when empty', which goes beyond annotations to warn about a serious side effect.

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 succinct sentences. First sentence states the purpose, second adds a crucial warning. No unnecessary words.

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

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

The description explains the core action and a critical edge case but omits details about return values and the specific operations (list/add/remove). Given 5 parameters, no output schema, and destructive hint, more context would be beneficial.

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?

Only 2 of 5 parameters have descriptions in the schema (dataType, expression). The description does not add any parameter-level guidance beyond what is already in the schema. The meaning of 'operation', 'tableName', and 'measureName' remains implicit.

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 manages extension measures (report-level DAX) in reportExtensions.json, with a specific verb 'manage' and resource. It distinguishes from sibling tools that deal with visuals, pages, etc.

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

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

No guidance on when to use this tool versus alternatives. While the purpose is clear, it does not mention when not to use it or provide context for selection among siblings.

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

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

Annotations (readOnlyHint=true) indicate no destructive side effects. Description adds that it generates an HTML dashboard, a non-obvious behavioral detail. No contradictions. Could mention that it modifies nothing, but safe assumption given readOnlyHint.

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 succinctly describes outputs, second provides prerequisite and recommended prior call. Every sentence serves a purpose 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?

Covers purpose, prerequisites, parameter behavior, and output type (HTML dashboard). Slightly lacking on where the dashboard is saved or how to access it, but given the output schema existence, this is acceptable.

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 100% with detailed descriptions for both parameters. The description adds no further semantic value beyond what the schema already provides, so baseline 3 is appropriate.

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

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

Description clearly states the tool cross-references the semantic model with the report, showing measure/column usage, DAX dependencies, unused fields, and per-page coverage. It also mentions generating an HTML dashboard. This distinguishes it from siblings, which focus on page, visual, or theme manipulation.

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

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

Explicitly states the prerequisite of a sibling .SemanticModel/ folder and instructs to call pbir_get_report first to check hasSemanticModel. This provides clear when-to-use guidance and an alternative path if the condition is not met.

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 only openWorldHint: false, so the description must disclose behavioral traits. It states that the tool mutates (move/resize), but omits potential side effects like layout impacts, permission requirements, or whether coordinates are absolute/relative. This lacks sufficient behavioral detail 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?

The description is a single sentence, effectively communicating the core function without fluff. However, it could be slightly more structured by optionally adding usage tips without significant length increase.

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 7 parameters, low schema coverage, no output schema, and no annotations, the description fails to provide adequate context. It does not explain that only visualId is required, that pageId auto-resolves, or describe coordinate/unit systems, leaving significant gaps for correct tool 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 only 43% (only z, pageId, visualId have descriptions). The description adds no parameter-level details beyond the schema, failing to explain x/y units, width/height meaning, or z-order semantics. With low coverage and no compensation, the agent lacks essential 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 'Move and/or resize a visual on a page' clearly states the verb (move and/or resize) and resource (visual). It directly introduces the tool's functionality and distinguishes it from sibling tools like pbir_set_visual_title or pbir_delete_visual, which handle other aspects.

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

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

No explicit guidance on when to use this tool versus alternatives. While the name and description imply it is for repositioning/resizing, there is no mention of prerequisites, exclusions, or comparisons to other visual manipulation tools, leaving the agent without clear contextual cues.

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 warns that unsaved work is lost, even adding detail about modeling-MCP measures not flushed by autosave. Annotations already mark destructiveHint: true, so the description significantly adds behavioral context beyond annotations.

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

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

The description is two concise sentences, front-loading the core action then adding crucial safety and usage details. Every sentence earns its place with no wasted words.

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

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

Given only one parameter, no output schema, and annotations providing destructiveHint, the description is fully complete. It covers purpose, usage, safety, and parameter behavior adequately.

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 100% for the single parameter. The description adds value by explaining the semantic difference between confirm=true (execution) and false/omitted (warning), which is not fully captured in the schema's description.

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

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

The description clearly states the tool reloads a report by closing and reopening the .pbip file. It distinguishes itself from sibling tools by explicitly mentioning it closes PBIDesktop.exe, which is unique among the listed 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 explains that confirm=true is required to proceed, and when false/omitted it returns a save-first warning. It provides clear context for use but does not explicitly state when not to use it or list alternatives beyond the save-first flow.

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 destructiveHint annotation already indicates mutation; the description adds no new behavioral context beyond stating the action 'Remove'. It does not discuss permissions, reversibility, or 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 a single clear sentence, front-loading the action and scope. It is concise and well-structured with no unnecessary words.

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

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

For a simple removal tool with no output schema, the description adequately covers the functionality. It could reference the origin of filter names (pbir_list_filters) but the schema already provides that 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 100%, so the parameter meanings are fully defined in the schema. The description adds no additional semantic value beyond what is already in the parameter descriptions.

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

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

The description clearly states the tool removes a specific filter by name from a page or visual, providing a specific verb and resource. It distinguishes itself from sibling tools like pbir_clear_filters (which removes all filters) by specifying 'specific filter by name'.

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

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

The description implies when to use (when you need to remove a specific filter), but does not explicitly state when not to use or provide alternatives. Sibling tools like pbir_clear_filters offer contrasting functionality, but no direct comparison is given.

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

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

Discloses that the theme file is kept but unlinked, adding context beyond the destructiveHint annotation. No contradictions.

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

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

Two sentences, no wasted words. First sentence states core action, second provides important side effect. Efficient 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?

For a zero-parameter tool with annotations, the description fully covers the effect and side effect. No output schema needed as return is likely void/success.

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

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

No parameters; schema coverage is 100% by absence. Description adds no parameter information but none is needed. Baseline 4 for zero-parameter tools.

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

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

Clear verb+resource: 'Remove the custom theme from the report, reverting to the default base theme.' It distinctly describes the action and distinguishes it from sibling tools like pbir_set_report_theme or pbir_get_report_theme.

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?

Implies usage when removing a custom theme, but no explicit guidance on when to use versus alternatives (e.g., pbir_set_report_theme for changing theme), nor any conditions or exclusions.

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

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

Annotations are minimal (openWorldHint=false), so the description should disclose behavioral traits. It does not mention what happens if the bookmarkId is invalid, any side effects, or required permissions.

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

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

The description is a single, concise sentence. It is front-loaded and to the point, though it could be slightly more informative without losing conciseness.

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

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

For a simple rename operation, the description is minimally adequate. However, it lacks context about the tool's relationship to other bookmark tools and any constraints (e.g., bookmark must exist).

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 100% with descriptions for both parameters. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Rename' and the resource 'existing bookmark', making the purpose unambiguous. It distinguishes itself from siblings like pbir_add_bookmark and pbir_delete_bookmark.

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 (e.g., pbir_add_bookmark for creating), nor does it mention prerequisites or post-conditions.

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

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

The description does not go beyond stating the basic operation. No annotations (destructiveHint, readOnlyHint) are present, so the description carries full burden but provides no extra behavioral details (e.g., whether renaming affects references, if it is reversible).

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, short sentence. It is concise but lacks important context. It is not overly verbose, but may be too terse for an agent to fully understand the operation.

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 rename operation with two parameters fully described in the schema, the description is minimally adequate. However, it does not mention the return behavior (e.g., no output schema) or edge cases (e.g., what happens if page not found).

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

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

The input schema has 100% description coverage for both parameters. The description adds no further meaning beyond the schema. Baseline score of 3 is appropriate.

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 'Rename an existing page' clearly states the action and resource. It is specific enough to distinguish from sibling tools like 'pbir_rename_bookmark' or 'pbir_set_page_visibility', though it does not explicitly contrast them.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., pbir_create_page, pbir_duplicate_page). No prerequisites or context are mentioned.

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