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

No annotations are provided, so the description carries the behavioral burden. It transparently discloses the lint gate blocking writes, the fail_on_severity default, and dry_run behavior. However, it doesn't explain what happens on success (return value), whether existing measures are overwritten, or any required permissions, leaving gaps.

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

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

Two sentences, front-loaded with the core action and immediate context about the lint gate. The dry_run explanation is useful and directly attached to the relevant parameter. Could be slightly more structured (e.g., listing key params) but is appropriately brief.

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

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

With 11 parameters sin which schema coverage is 0%, the description leaves most parameters unexplained, including target, measure_name, expression, is_hidden, runtime_check, and measure_writer. It also references fail_on_severity in the description but that parameter does not appear in the input schema, which is confusing. No output schema existsandar the description doesn't state what successful execution returns, so an agent lacks key info to confidently call this tool.

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

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

Schema description coverage is 0% with 10 parameters, so the description must compensate. It only clarifies fail_on_severity and dry_run. Worse, fail_on_severity is mentioned but not present in the input schema while other params like runtime_check, measure_writer, and format_string remain 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 identifies the tool's job: 'Add a DAX measure with mandatory lint validation.' It uses a specific verb and resource, and the validation detail sets it apart from a plain add-measure tool. However, it doesn't explicitly name a sibling it differs from, so it falls just short of full differentiation.

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

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

The description explains the lint gate behavior and the dry_run option, which implies the intended workflow: use this to add measures with validation, or dry-run to preview findings. It does not explicitly state when not to use this tool or name a better alternative among siblings, leaving the selection reasoning partially 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states the tool executes a plan and includes automatic rollback on failure, which is a key behavioral trait. It also explains the dry_run behavior (no side effects, uses a dry-run executor) and notes that confirm_each_step is not enforced. However, it doesn't disclose potential side effects beyond that, such as whether the plan is idempotent or what happens to partially executed steps beyond rollback. The behavior is partially transparent but not fully.

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

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

The description is concise and structured with clear sections for summary, args, and returns. The summary is front-loaded, which helps agents quickly grasp the purpose. The args section is efficient, using bullet points for clarity. The only minor issue is that the returns section is brief, but that's acceptable given an output schema exists. Overall, every sentence adds value without fluff.

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

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

Given the tool's complexity (it executes plans with rollback) and the existence of an output schema, the description covers essential details: purpose, parameters, and behavior. The description also clarifies the status of confirm_each_step, which is important to avoid confusion. Since an output schema is present, the lack of detailed return information is acceptable. An agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must fully explain the parameters. It does so comprehensively: plan_id is explained as the ID of a plan created by plan_change; dry_run is described with its behavior (no side effects, dry-run executor used); confirm_each_step is explained as reserved for v2 and not enforced. This goes beyond the schema's bare definitions and gives agents the necessary context to use the parameters correctly.

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

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

The description clearly states the tool's purpose: executing a plan with automatic rollback on failure. It identifies the specific resource (plan) and the action (execute), and mentions plan_id as the identifier of a plan created by plan_change. This distinguishes it from siblings like plan_change (which creates plans) and pre_deploy_check (which likely validates before execution).

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

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

The description implies usage by stating the plan_id must reference a plan previously created by plan_change, which gives context on when to use this tool. However, it doesn't explicitly state when not to use it or mention alternatives. There is no guidance on when to use dry_run vs. normal execution, though the parameter description hints at it. A clear exclusion or alternative mention would improve this.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the three main effects—theme application, alt-text backfill, and WCAG re-audit—but it does not say whether existing themes or alt text are overwritten, whether changes are persisted in place, or what happens as a result of the re-audit.

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 compact sentence that front-loads the main action and decomposes the operation into three clear parts. It is efficient and scannable, though the heavy use of '+' reads more like a label than a fully structured explanation.

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 four parameters, zero annotations, and no parameter-level documentation, the description is not complete enough for an agent to invoke the tool with confidence. It omits prerequisites, side effects, and any indication of what the WCAG re-audit returns or writes back, even though an output schema exists.

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

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

Schema description coverage is 0% and the description does not explain the parameters. It loosely connects 'theme' to palette and 'alt text' to alt_text_template/auto_backfill_alt_text, but it never explains allowed palette values, how the template is evaluated, or the effect of setting auto_backfill_alt_text to false.

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

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

The description names a specific multi-step operation: applying a colorblind-safe theme, backfilling alt text, and re-auditing WCAG. This makes the tool's purpose understandable and distinguishes it from siblings like edit_report_visual or audit_report_ux_and_storytelling, though it does not explicitly contrast itself with 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?

There is no guidance on when to use this tool versus alternatives, no prerequisites like required report state, and no indication of whether it should run before or after other audit/theme tools. The description states what the tool does but not the conditions under which an agent should select 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 no annotations, the description must carry the behavioral disclosure burden, but it only says 'audit' without explaining whether the tool writes outcomes, needs a workspace connection, is read-only, or has side effects. It also does not clarify how the PBIP folder is located or consumed.

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?

One clear sentence with no filler; the acronyms in parentheses quickly convey the audit types and the target is stated up front. 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?

There are 7 parameters, no annotations, and no parameter descriptions, yet the description offers only a high-level summary. An agent would not know how to configure bpa_ruleset, dax_measures_json, or which boolean toggles are available, so it is materially incomplete 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 0%, so the description must compensate, but it only maps loosely to bpa, dax_lint, and accessibility. It leaves naming, bpa_ruleset, and dax_measures_json unexplained, and gives no detail about toggle semantics or how to supply a ruleset or measures JSON.

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

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

The description names a specific verb ('audit'), a concrete resource ('PBIP folder'), and the exact audit dimensions ('BPA + DAX lint + WCAG'). This clearly distinguishes it from sibling audit_report_ux_and_storytelling, whose focus is UX/storytelling rather than model/report compliance.

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

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

The description gives no when-to-use or when-not-to-use guidance, and names no alternative tools. It implies use for composite audits, but does not explain how it compares to pre_deploy_check, audit_report_ux_and_storytelling, or apply_theme_and_accessibility_rules.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses the tool's core behavior: reading PBIR pages, producing a 0-100 score, category breakdown, per-finding suggestions, and configurable strictness. This is reasonably transparent for a read-only auditing tool, though side effects or prerequisites are not discussed.

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

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

The description is compact and front-loaded: it opens with the tool's role, then states inputs and outputs, then notes a key option. Each sentence adds distinct value with minimal verbosity.

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 output format (0-100 score, category breakdown, suggestions) and strictness, but it does not explain key parameters like 'audience_assumed' or clarify what a 'PBIR path' refers to. With no output schema or annotations, an agent would still have to infer some invocation details.

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

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

The schema provides only titles and defaults, with no descriptions, so the description must compensate. It explains 'strictness' with allowed values, but it does not clarify 'pbip_path', 'page_name', or 'audience_assumed'. Since these parameters are otherwise undocumented, the description leaves significant gaps.

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

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

The description uses a specific verb ('audits'/'scores') and identifies the resource ('PBIR pages') and focus (hierarchy/density/narrative/mobile/cohesion). It clearly distinguishes this as a heuristic qualitative UX/storytelling audit tool, though it does not explicitly differentiate it from the sibling 'audit_model_and_report'.

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

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

The description implies when to use this tool (for qualitative UX and storytelling assessment of Power BI reports), but it provides no explicit guidance on when not to use it or how it compares to alternatives like 'audit_model_and_report' or 'optimize_report_performance'. Usage context is present but exclusionary criteria are absent.

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

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

The description discloses key behaviors: it reads workspace state via fabric_client.snapshot_workspace, commits each item as <type>/<name>.pbip, warns on uncommitted changes or large files, and dry_run skips the commit. Since no annotations are provided, the description carries the full burden, and it does a good job explaining side effects and safety mechanisms. It could add more detail about what happens to existing commits or how the repo is initialized, but it is quite transparent for a snapshot/commit tool.

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

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

The description is concise and well-structured: a one-sentence summary followed by two sentences of key behavioral details. It front-loads the core purpose and then adds important caveats (warnings, dry_run). Every sentence earns its place, and the format is easy to scan.

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

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

The tool has 6 parameters, no annotations, and an output schema. The description covers the main workflow and safety behaviors, but it does not explain the output schema or the exact role of parameters like branch and exclude_items. Given the complexity of a Git commit operation, a bit more detail on parameter effects and the output would make it complete. Still, it is largely sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the 6 parameters. It mentions dry_run and the commit behavior, but it does not explain the meaning of workspace_id, output_repo_path, branch, exclude_items, or commit_message beyond what their names imply. The description adds some context (e.g., dry_run skips the commit) but leaves most parameter semantics to the schema, which has no descriptions. This is a clear 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 the tool's purpose: 'Snapshot a Fabric workspace into a local Git repo.' It specifies the verb (snapshot/commit), the resource (Fabric workspace), and the destination (local Git repo). It also distinguishes itself from sibling tools like sync_git_to_workspace by focusing on committing workspace state to a local repo, not syncing from Git.

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: when you need to snapshot a workspace into a local Git repo. It mentions 'Warns on local uncommitted changes or large files' and 'dry_run skips the commit,' which gives context for safe usage. However, it does not explicitly state when not to use it or name alternative tools like sync_git_to_workspace, so it falls short of a 5.

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

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

Even without annotations, the description conveys key behavior: it creates a connection/session, detects engines, returns warnings, and supports distinct auth modes. It could add lifecycle/side-effect detail (e.g., interactive prompts, session persistence), but it is substantive.

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 doc-style Args/Returns format is compact and scannable; every line adds information without bloat.

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

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

All parameter semantics and the return structure are covered, and sibling tools make the connective role understandable. It could add prerequisites or side effects but is largely complete for 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?

The schema has zero descriptions, but the description compensates by enumerating target_type values, explaining target_ref, listing auth_mode options, and flagging tenant_id as service-principal-only.

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

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

Clearly states the tool connects to a Power BI target and detects available engines. The allowed target_type values and the expected result (session_id, engine list) make the purpose concrete.

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 this should be called, whether it is a prerequisite for other tools, or which target/auth mode to choose under different circumstances.

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

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

With no annotations, the description provides some transparency by stating it never overwrites existing files and returns warnings. However, it does not disclose other behaviors such as permission requirements, effects on the source dataset, or the nature of warnings, leaving gaps.

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

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

The description is two sentences with no filler, front-loaded with the core purpose and key behavioral constraint (no overwriting). 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?

Despite having an output schema, the description lacks essential context: it does not describe the parameters, any prerequisites, or how the tool integrates into the workflow. Given six parameters and no schema descriptions, this is insufficient 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 0%, and the description does not explain any of the six parameters (e.g., what pbip_path should be, what theme options are, the meaning of visual_count). The titles alone are insufficient for an agent to correctly populate 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 'scaffold' and the resource 'PBIR folder from an existing dataset', listing specific files created. This distinguishes it from sibling tools like edit_report_visual or design_report_page_from_requirements, which focus on different 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 implies usage for creating a new report scaffold but does not explicitly state when to use this tool over alternatives, nor does it mention any prerequisites or conditions. The context is clear but not explicitly framed against other options.

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

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

With no annotations provided, the description carries the full burden, and it discloses a good deal: the exact validation pipeline (Pydantic + dangling-reference check + basic DAX lint), the atomic write behavior, the two dry-run modes, and the output fields. It does not contradict any annotations. Minor gaps remain (e.g., failure behavior in write mode), but the core behavioral profile is well covered.

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

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

Two tight paragraphs: the primary purpose is front-loaded and the second paragraph details behavior, mode selection, and output fields. Every sentence earns its place with no filler or repetition.

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

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

Given an output schema exists, the return format is largely covered. The description fully explains the validation flow, the atomic write, and mode selection. It falls slightly short on clarifying input-format requirements and what happens on validation failure, but for a tool of this complexity with no annotations, it is substantially complete.

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

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

Schema coverage is 0%, so the description must compensate. It explicitly explains dry_run ('returns the validation result (dry_run=True) or atomically writes (dry_run=False)') and implies output_pbip_path via the PBIP layout mention. However, it never directly clarifies the distinction between spec_json and spec_yaml (both are input spec formats) or what the output path expects, leaving two parameters only vaguely connected.

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 opening sentence states a specific verb ('Generate') and resource ('TMDL semantic model from a declarative spec'), and the second paragraph adds the validate-vs-write dual behavior. No sibling tool creates a semantic model from a spec, so it is implicitly distinguished from deploy, refresh, diff, and planning tools.

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

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

The description conveys the two operational modes (dry_run=True validates and returns; dry_run=False atomically writes PBIP layout), which gives clear behavioral context. However, it never states when to prefer this tool over alternatives, when not to use it, or prerequisites like needing the spec in a particular format.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description says 'publish PBIP' and 'configure refresh' and 'initial refresh', but it does not disclose what the gate does when it fails (does it abort?), what happens to existing workspace content (overwrite or create new), whether configuration is destructive to existing refresh settings, or how authentication credentials are used. For a multi-step deployment tool with side effects, this is a significant gap.

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 declarative sentence that front-loads the core purpose (pre-deploy gate) and lists subsequent actions in order. No redundant words; every word earns its place. It is appropriately sized for a tool that orchestrates multiple sub-operations.

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

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

Given the tool's complexity (10 parameters, multiple operations, no output schema details provided), the description is under-specified. It omits criteria for gate success/failure, dependencies among operations, cleanup behavior, and effect on existing workspace content. The existence of an output schema (though not shown) may clarify return values, but the description does not cover prerequisites, preconditions (e.g., PBIP exists, valid path), or behavior in mock mode. A 3 indicates room for improvement.

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

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

Schema description coverage is 0%, so all parameters are undocumented in the schema. The description names 'PBIP' and 'refresh' but does not specify which parameters control the gate (e.g., 'gate_profile', 'findings_json'), the publish (e.g., 'pbip_path', 'workspace_id'), refresh configuration ('refresh_daily_hour'), or authentication ('client_id', 'tenant_id', 'client_secret', 'auth_mode'). The 'mock' parameter's purpose is not explained. The description does not compensate for the lack of schema descriptions, but the parameter names themselves are fairly self-explanatory, giving a 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 lists four distinct actions: pre-deploy gate, publish PBIP, configure refresh, and initial refresh. Each is a specific verb plus resource, making the tool's purpose clear. It distinguishes from siblings like 'pre_deploy_check', 'run_refresh', and 'promote_in_pipeline' by combining these actions into a single orchestrating tool.

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

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

The sequential actions imply a clear workflow: run the gate before publishing, configure refresh after publish. However, there is no explicit mention of when NOT to use this tool or when a sibling like 'pre_deploy_check' or 'run_refresh' should be used instead. The context signal of sibling tools suggests alternatives, but the description does not name them.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only hints at side effects with 'for actual file I/O' but does not explain whether it overwrites existing PBIR content, what happens to existing visuals, or what changes are made to the file system.

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

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

The description is compact and front-loaded with the core capability. However, the second sentence introduces unclear internal component names ('viz/visual_suggester', 'python_report') without explanation, which reduces clarity despite the concise length.

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

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

For a tool with six parameters, no schema descriptions, and no annotations, the description is under-specified. An agent cannot determine the meaning or expected values of optional parameters, the effect of execution, or the conditions under which this tool should be preferred over related report-editing siblings.

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

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

Schema description coverage is 0%, and the description does not compensate. It references 'NL brief' and PBIR page context, which loosely maps to brief and pbip_path, but it says nothing about palette, audience, inspector, or page_name, leaving five of six parameters semantically 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 first sentence clearly states the verb ('Synthesize'), the resource ('a PBIR page'), and the input ('an NL brief'), which distinguishes it from sibling tools like create_report_from_dataset or edit_report_visual. However, 'Synthesize' is slightly abstract, and the implementation note about 'viz/visual_suggester + python_report' is jargon-heavy and does not sharpen the core purpose.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as create_report_from_dataset or edit_report_visual. It names no preconditions, exclusions, or selection criteria, so an agent must infer suitable usage from the name alone.

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

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

No annotations are provided, so the description carries the burden. The verb 'Diff' reasonably implies a read-only comparison rather than a mutation, and the accepted input kinds are stated. However, it does not explicitly disclose whether inputs are modified, what access is required, or how the comparison behaves when inputs are incompatible.

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 filler. Every word adds value, especially the parenthetical that constrains the accepted input types. This is appropriately concise for a relatively simple tool.

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 minimally viable for the main use case: an agent can infer that before and after are the two things to compare. The output schema covers return values, so not describing them is acceptable. However, the tool lacks usage guidance and leaves the optional inspector parameter undocumented, making the overall context incomplete.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify that 'before' and 'after' refer to two semantic models in PBIP folder or snapshot form, which is useful. But the optional 'inspector' parameter is left completely unexplained, and no format or syntax details for the string values are provided.

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

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

The description clearly states a specific verb and resource: 'Diff two semantic models.' The parenthetical '(PBIP folders or snapshots)' sharpens the input scope and helps the tool stand apart from deployment/refresh/reporting siblings. It doesn't explicitly contrast with any sibling, but no other sibling is a compare-style operation.

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

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

There is no guidance on when to prefer this tool over alternatives, such as using it before plan_change or apply_plan. The description merely states what the tool does, leaving intended usage context and exclusions to inference.

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

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

Annotations are absent, so the description carries the full burden, and it delivers: 'Deterministic' signals idempotent/repeatable behavior, 'field-level merge' discloses that unspecified fields are preserved (non-destructive scope), and 'atomic write via temp-then-rename' reveals write safety. It stops short of disclosing permission requirements or failure/rollback behavior, but the core behavioral contract is unusually well stated.

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

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

Three short sentences with zero filler. Purpose is front-loaded in sentence one, followed by the two behavioral constraints (merge scope, atomic write) that matter most. Every sentence earns its place.

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

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

Given the complexity of 9 parameters with 0% schema coverage, the description covers the essential behavioral contract (what changes, what's preserved, write safety) and an output schema exists so return values need no explanation. Yet the JSON parameter formatting is unresolved, and for a 9-param tool with no other documentation this leaves an agent guessing on how to supply field/format/position content.

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

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

Schema coverage is 0%, so the description must compensate, and it partially does: the field-level merge statement clarifies that omitted optional params (type, alt_text, is_hidden, fields_json, format_json, position_json) are preserved rather than reset. However, it does not explain the content or syntax of the JSON-string params (fields_json, format_json, position_json), leaving a meaningful gap for an agent constructing input.

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

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

The description states a specific verb (edit) and resource (single visualContainer in a PBIR page), fenced by 'Deterministic', which correctly distinguishes it from non-editing siblings like run_refresh or deploy_to_workspace. However, it does not explicitly name any sibling or contrast criterion, so differentiation is implicit rather than stated.

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

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

No when-to-use or when-not-to-use guidance is provided. There is no mention of alternatives despite 25 siblings that touch report visuals (select_visuals_for_kpis, design_report_page_from_requirements, apply_theme_and_accessibility_rules), nor any prerequisite or context on when this edit tool is the appropriate choice. The agent is left to infer applicability.

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

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

No annotations exist to cover side effects or permissions. The description only says it generates a Markdown data dictionary with Mermaid ER diagram. It doesn't state whether it writes to a file, whether it overwrites output, whether it connects to a PBIP path, or any other behavioral details. The burden is on the description, and it only covers the high-level output.

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?

One concise sentence with a clear verb and object. No fluff. Loses a point because it omits any parameter or usage context that would help an agent.

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 gives no guidance on when to use this tool versus alternatives, does not explain parameters or prerequisites, and does not specify side effects (e.g., file output location). Given no annotations and no output schema, this is too sparse for an agent to invoke with confidence.

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

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

Schema coverage is 0% (no parameter descriptions). The description mentions 'for a PBIP' which hints that pbip_path identifies the PBIP, but inspector and output_path are completely unexplained. No compensation for the schema gap, so below baseline.

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 ('Generate') and the resource ('a Markdown data dictionary with Mermaid ER diagram for a PBIP'). It is distinct from sibling tools like deploy_to_workspace or audit_model_and_report, though it doesn't explicitly name an alternative or scope. The verb and resource are specific enough for basic identification.

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, what inputs are expected, prerequisites, or how it differs from alternatives. An agent gets no direction on choosing it over siblings.

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

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

No annotations are present, so the description carries the burden. It discloses that the tool is heuristic, read-only in spirit ('Reads pages/*/page.json'), and describes the output shape (0-100 score, estimated load, hotspots with severity). It doesn't state side effects explicitly, but reading behavior is clearly implied.

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

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

Two tight sentences: the first states the tool's domain; the second covers inputs, scan pattern, and output. No filler or redundant restatement.

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

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

Covers purpose, method, and output sufficiently, and the output schema likely fills return-value details dash; however, the missing target_load_ms semantics and any guidance about when to use/avoid it leave a noticeable gap for a tool with no annotations and 0% parameter coverage.

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

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

Schema coverage is 0%, and the description only indirectly clarifies pbip_path via the pages/*/page.json read pattern. target_load_ms is not mentioned at all, leaving agents to guess how the threshold is used in scoring or hotspot classification.

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 identifies the tool as a heuristic performance analyzer for PBIR pages, states the specific files it reads, and names the anti-patterns it detects. This makes its function and scope unambiguous relative to sibling tools.

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

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

The description gives clear context (use when analyzing perceived load of PBIR pages), but it never explicitly states when not to use it, prerequisites, or alternatives. It doesn't mislead, but the guidance is implicit rather than directive.

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

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

With no annotations provided, the description carries full behavioral burden. It adds useful context, such as PlanOptions fields being extracted before template args are passed, and the return fields (plan_id, plan_yaml, etc.). However, it does not explicitly disclose side effects or the lack thereof, such as whether the workspace is modified, which is important for a planning tool operating alongside execution siblings.

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

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

The description is well-organized with an opening summary, Args section, and Returns section. It is appropriately concise and every section adds value, though the template-specific arguments list could be more complete without bloating this section.

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 two top-level parameters well and references the output schema's fields. However, the options object is open-ended and template-specific required args are only illustrated for one of four templates, leaving an agent to guess what to supply for audit, deploy, and dax_regression. This is a notable gap given the schema itself provides no help.

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 provides no property descriptions (0% coverage), so the description must compensate—and it does. It explains intent as one of four templates and details options with a concrete safe_rename example, plus mentions PlanOptions extraction. This goes well beyond the bare schema, though it does not enumerate required args for the other three templates.

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 leads with a specific verb-resource pair: 'Create a versionable plan from a template name + structured args.' It names the four MVP templates and clarifies that this tool produces a plan rather than applying or auditing, distinguishing it from siblings like apply_plan and audit_model_and_report.

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

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

The description does not explicitly state when to use plan_change versus alternatives, such as 'use this before apply_plan' or 'use apply_plan to execute the generated plan.' The intent is implied by the word 'plan' but no direct usage guidance or exclusions are 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'evaluate findings,' which suggests a read-only check, but it does not state whether the tool mutates state, what the gate outcome means, or what an agent should expect on pass/fail.

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 is concise, though slightly under-specified, which is a separate completeness issue rather than a conciseness flaw.

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

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

Given no annotations, 0% schema description coverage, and an output schema that may explain return shape, the description still lacks necessary operational context. An agent cannot tell what a gate profile is, what findings_json must look like, or when in the deployment workflow this tool should be invoked.

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?

Input schema coverage is 0%, and the description adds only minimal context: 'findings' loosely maps to findings_json and 'pre-deploy gate profile' loosely maps to profile. It does not explain valid profile values, the expected JSON shape of findings, or how effects differ across profiles.

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

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

The description uses a specific verb and resource: it says the tool evaluates findings against a pre-deploy gate profile, which clearly identifies the core action. It does not reference sibling tools or distinguish itself from related deployment/audit tools, so it does not earn a 5.

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

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

The description gives no guidance on when to run this check versus alternatives like audit_model_and_report, plan_change, or deploy_to_workspace. The name 'pre_deploy_check' implies it belongs before deployment, but no prerequisites, exclusions, or alternative conditions are stated.

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

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

With no annotations provided, the description must fully disclose behavioral traits. It mentions injected gates and dry-run behavior when fabric_client is absent, but it does not disclose side effects of promotion, permission requirements, reversibility, or what happens on failure. The mutation aspect is not elaborated, and the dry-run mention is the only safety signal. This is insufficient for a state-changing tool.

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

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

The description is concise (two sentences) and efficient, but it lacks structure and prioritizes the mechanism (gates, dry-run) over essential user-facing information like parameters and usage. It is appropriately short but under-specified for the tool's complexity.

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 five parameters, a complex injection model, and an output schema, the description is severely incomplete. It does not explain the parameters, the output schema, or when to use the tool. It mentions gates and dry-run but provides no operational context. The tool appears to be a high-level orchestration, yet the description leaves critical details undefined.

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

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

Schema description coverage is 0%, meaning the description provides no explanation for any of the five parameters (items, dry_run, pipeline_id, source_stage, target_stage). It does not even mention them by name. The description only references an injected fabric_client, which is not in the schema. The description fails to compensate for the missing parameter documentation.

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

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

The description states a clear action and resource: 'Promote items between Fabric Deployment Pipeline stages.' This distinguishes it from siblings like deploy_to_workspace and plan_change, which target different deployment operations. However, it doesn't specify what 'items' are or what stage promotion entails, so it's slightly generic but still 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 provide any guidance on when to use this tool versus alternatives. It mentions built-in gates wrapping other tools but doesn't explain when to invoke promote_in_pipeline directly or when to use those sub-tools. No exclusions or conditions are stated, leaving usage ambiguous.

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

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

With no annotations, the description carries the full burden. It mentions that it returns a plan and optionally writes the calc group if auto_apply=True, but it omits critical behaviors like whether original measures are preserved (preserve_originals), how reconcile_strategy affects the outcome, and any side effects beyond the write. This is minimal disclosure for a mutation-capable tool.

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

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

The description is two sentences with no fluff, front-loading the purpose and an example before the outcome. It is concise and readable, though it sacrifices detail for 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 tool with 7 parameters, no schema descriptions, and no annotations, the description is severely incomplete. It does not explain the role of most parameters, the nature of the returned plan, or the side effects beyond an optional write. Even with an output schema present, an agent cannot reliably invoke this tool based on the description alone.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It only touches auto_apply implicitly (via the 'if auto_apply=True' clause) and ignores target, inspector, measure_writer, min_candidates, preserve_originals, and reconcile_strategy. This provides virtually no help for an agent selecting correct arguments.

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 (detect and consolidate) and the resource (measures into a calculation group), with a concrete example of shared structure (X YTD/QTD/MTD). It is distinct from siblings like plan_change or apply_plan, but does not explicitly name an alternative, so it stops short of a 5.

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

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

The description implies usage when measures share structural patterns, giving context but no explicit guidance on when not to use or which alternative to pick. It does not reference sibling tools or prerequisites, so the guidance is only implied.

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

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

With no annotations, the description must carry safety and side-effect disclosure. It states that it runs queries and diffs results, but gives no information about whether this requires an active connection, whether it writes any artifacts, what happens when queries fail, or what tolerance_pct does. The behavioral surface is largely unexplained.

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 filler. It is appropriately compact for a tool whose purpose is stated in one line, although this brevity comes at the cost of completeness.

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

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

For a tool with four parameters, no annotations, and a broad sibling list, this one-line description is incomplete. It fails to explain how queries_json should be structured, what baseline_path must contain, the meaning of tolerance_pct, or when the tool should be selected over diff_models. The presence of an output schema doesn't compensate for missing input and usage guidance.

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

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

Schema description coverage is 0%, so the description must compensate. It maps loosely to queries_json and baseline_path via 'DAX queries' and 'baseline JSON', but tolerance_pct and query_executor are never mentioned and no formats or constraints are given. This leaves an agent guessing at required input semantics.

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

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

The description identifies the action: execute DAX queries and compare the results against a baseline JSON, producing a diff. This clearly distinguishes it from siblings like diff_models by tying the operation to query results and a baseline file. It is specific, though it doesn't explicitly name alternatives.

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

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

There is no guidance on when to use this tool, when not to use it, or how it relates to siblings such as diff_models or run_refresh. The word 'regression' implies testing, but the description never states prerequisites (e.g., an existing baseline file) or 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool triggers a refresh and can wait, but it does not disclose what happens during the wait, whether the refresh is asynchronous by default, what the output schema contains, or any side effects (e.g., whether it blocks other operations). The 'optionally wait' hint is useful but insufficient for a tool with 9 parameters and no annotation support.

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 with the primary action and the optional wait behavior. It is appropriately concise and does not waste words, though it could be slightly more informative without becoming verbose.

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 9 parameters, no annotations, and an output schema, the description is too sparse to be complete. It does not explain the refresh types, the meaning of waiting, the timeout behavior, or the authentication parameters. An agent would likely need to inspect the schema and possibly external documentation to use this tool correctly. The output schema exists, so return values are not the main gap, but the behavioral and parameter context is missing.

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

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

Schema description coverage is 0%, so the description must compensate for the 9 parameters. It does not explain the meaning of key parameters like 'wait', 'refresh_type', 'timeout_s', or the auth-related fields. The description only mentions 'optionally wait', which maps to the 'wait' parameter, but leaves the rest unexplained. This is a significant gap for an agent trying to invoke the tool correctly.

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

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

The description 'Trigger and optionally wait for a dataset refresh' clearly identifies the action (trigger) and the resource (dataset refresh), and the 'optionally wait' clause distinguishes it from a simple fire-and-forget trigger. It is concise and understandable, though it does not explicitly differentiate it from sibling tools; however, the verb 'run_refresh' and the resource 'dataset refresh' are specific enough to avoid confusion with 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 implies usage: trigger a refresh and optionally wait for completion. It does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. Given the sibling list includes many other operations, some guidance on when a refresh is needed would be helpful, but the description's brevity still conveys the core use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It covers the best-effort caveat, fallback output mode, platform/dependency requirements, and the rendering_warnings signal. It doesn't mention file-write side effects or permissions, but the most non-obvious behavioral traits are honestly disclosed.

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

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

The description is compact and front-loaded: a one-sentence purpose followed by the critical caveats in a second paragraph. There is no filler, repetition of schema fields, or irrelevant detail.

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

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

The core behavior and fallback path are explained well, and an output schema exists so return-value details are less critical. However, the six parameters are semantically undocumented, and the description doesn't fully bridge that gap. It is a minimum-viable definition with meaningful missing context.

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

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

Schema description coverage is 0% and the description adds essentially no parameter-level meaning. It does not explain pages, format, wait_ms, output_dir, resolution, or how they relate to the fallback behavior. With six parameters and no schema descriptions, this is a major 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 opening sentence names a specific verb and resource: 'Best-effort screenshot capture of PBIR pages.' This clearly tells an agent what the tool does. It doesn't explicitly contrast with a sibling tool, but none of the listed siblings performs screenshot capture, so the scope is effectively 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 gives important context for when output is trustworthy: without the Power BI Desktop Bridge it produces SVG wireframes + JSON manifests, and real PNG/PDF requires superbi-mcp on Windows. It also signals a regression-diffing use case. It doesn't explicitly state exclusions or alternatives, but the prerequisites and degraded-output conditions are clear.

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

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

No annotations are provided, so the description must carry the burden. It reveals that it uses a specific recommender engine automatically, implying no manual visual selection. However, it doesn't disclose side effects or return format; output schema likely covers that. It is not contradictory.

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

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

The description is very short (two sentences) and gets straight to the point. It is front-loaded with the main output. It is efficient, though it lacks depth for a tool with no schema descriptions.

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 it has 4 parameters with zero schema documentation and no annotations, a two-sentence description is insufficient. With an output schema existing, the return structure is covered, but the parameters' semantics are unclear. For a tool that selects visuals, more context on audience and result limiting is 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 description coverage is 0%, so the description must explain parameters. The description only mentions 'KPI in the JSON list' (relating to kpis_json) but doesn't clarify the 'audience', 'inspector', or 'max_results' meaning. No parameter details are given beyond names.

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

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

The description states a clear purpose: for each KPI, return primary visual and alternatives. It mentions the underlying 'viz/visual_suggester' logic, which adds context. It doesn't explicitly differentiate from sibling tools but the KPI context is specific enough.

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?

Description gives no guidance on when to use this tool versus siblings. It does not mention preconditions (like having KPI data) or alternatives. The single sentence does not provide context for selection; it simply explains functionality.

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

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

With no annotations supplied, the description carries the full disclosure burden. It discloses several important behaviors: the operation is batched, requires an explicit admin scope, and names are SHA-256 redacted in outputs unless toggled. This goes well beyond a basic one-line summary, though it could still explain failure semantics or dry-run behavior more fully.

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

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

The description is compact and front-loaded: the core purpose is stated in the first sentence, followed by three high-signal behavioral details in a very small space. No sentence is filler, and the formatting makes the admin scope and redaction behavior immediately discoverable.

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 involves six parameters, no annotations, and zero schema coverage, which means the description needs to cover more operational context. It provides the endpoint, scoping, and redaction, but it does not clarify items format, the dry_run default, the meaning of both label_id and label_name, or allowed representative admin_scopes. This is likely too incomplete for safe autonomous invocation.

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

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

Schema description coverage is 0%, so the description must compensate for otherwise opaque parameters. It only meaningfully explains redact_names (and loosely touches on admin_scopes through the scope gate), leaving items, label_id, label_name, and dry_run without usable semantics. For a 6-parameter tool with no schema explanations, this is insufficient.

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 specific action ('Apply a Microsoft Purview sensitivity label to one or more items'), identifies the resource with a named verb, and indicates the batched nature through the endpoint reference. It is distinguishable from the sibling tools, which target different operations such as planning, deploying, or refreshing.

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

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

The description gives implicit usage context: it is an admin-gated, batched labeling operation, and it notes the required scope. However, it does not explicitly say when to choose this tool over alternatives or when not to use it. There is no usage guidance beyond the contextual prerequisite, so the guidance is implied rather than explicit.

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

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

With no annotations, the description must carry the full burden. It discloses that edits are written atomically to definition.tmdl and that failures can roll back when rollback_on_test_failure is True. However, it omits details about permissions, side effects on the model, or success behavior, making the transparency partial.

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

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

The description is two sentences, front-loaded with the primary action, and uses precise terminology. It is concise and well-structured, though it assumes familiarity with TMDL and test engines.

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 schema descriptions, no annotations), the description is incomplete. It does not explain how to provide the spec, what dry_run does, or what the output schema contains, leaving significant gaps 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 0%, so the description must compensate. It only mentions rollback_on_test_failure and test_query indirectly, but fails to explain target, spec_json, spec_yaml, or dry_run. This leaves the agent without adequate parameter meaning.

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

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

The description clearly states the tool applies RLS roles and members and runs a test matrix against a TMDL model, with specific actions like writing role blocks and validating the spec. This is a specific verb+resource statement that distinguishes it from siblings like deploy or refresh, which have different purposes.

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, nor any exclusions or prerequisites. It does not mention related tools or conditions that would make this the right choice, leaving the agent to infer its applicability.

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

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

With no annotations provided, the description must disclose behavioral traits. It mentions that conflicts are surfaced in 'items_skipped' for manual review, which is useful. However, it does not state whether the operation is mutating, what happens to existing workspace content, or any side effects. The odd phrase 'For v3 inicial' is confusing and the mention of 'pre_deploy_profile' arguments that are not in the schema adds noise without clarifying behavior.

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

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

The description is short but poorly structured. The first sentence is clear, but the rest contains a typo ('inicial'), an unclear reference to 'the MCP wrapper', and a sentence that seems to address developers rather than agents. It is not front-loaded with the most critical guidance, and every sentence does not earn its place. The content is confusing and detracts from the core 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 has 5 parameters (2 required) and an output schema, the description should provide enough context for an agent to call it correctly. It does not explain required parameters, the meaning of dry_run, or what the output contains (though 'items_skipped' is hinted). The description is insufficient for a deployment tool with multiple configuration options; an agent would likely struggle to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not explain any of the five schema parameters (repo_path, workspace_id, dry_run, branch_or_commit, conflict_resolution). It vaguely references 'pre_deploy_profile' and 'pre_deploy_findings' which are not even in the schema, leaving the agent without any understanding of what each parameter means or expects.

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

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

The description opens with a clear verb and resource: 'Deploy a local Git PBIP tree to a Fabric workspace.' This is specific and distinguishes it from reverse-direction siblings like commit_workspace_to_git. While deploy_to_workspace exists, the PBIP/Git specificity narrows the scope. The statement fully conveys the tool's core function.

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

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

The description provides context about conflict-resolution mode and mentions pre_deploy arguments, but it does not explicitly state when to use this tool versus alternatives like plan_change, apply_plan, or deploy_to_workspace. No exclusions or conditions are given. It implies use for local Git deployment but fails to guide selection among similar deployment-related tools.

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