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

With no annotations, the description carries the full burden and does well: it discloses that the tool is non-mutating, that unshortenable names are reported instead of forced, and that colliding proposals are auto-adjusted. It does not mention scope of scanning, permissions on the .pbip directory, or limits on proposal volume.

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?

Purpose is front-loaded in one sentence, and the Args/Returns structure is scannable. Some duplication exists between the trigger list and the Args block, but given 0% schema coverage the repetition 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 five-parameter, read-only proposal tool this covers what an agent needs: what it does, when to call it, each parameter's meaning, the non-mutating guarantee, and the handoff path to plan_change. An output schema exists, and the Returns note adds the useful downstream pointer rather than restating the shape.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: every one of the five parameters is explained, including the valid values for 'kind' ("measures", "columns", or "both") which the schema leaves as a bare string with no enum, plus the semantics of the length threshold and the two word-shortening flags.

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?

Specific verb and resource: 'Propose shorter names for the measures and columns that need them.' It also explicitly distinguishes itself from the mutating siblings by stating 'It does not rename anything', so an agent can tell it apart from plan_change/apply_plan without opening any schema.

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

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

The 'Use this tool when the user asks to' list gives three concrete trigger scenarios, including the preparatory case ('Prepare a batch of renames before applying them'). The handoff to plan_change(intent="safe_rename") names the downstream alternative explicitly, and the no-rename boundary rules out misuse.

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

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

With no annotations, the description carries the burden and does reasonably well: it explicitly states 'It does not write anything and does not apply the abstraction', and warns that the fix is context-dependent (calculation group vs helper table vs rewrite). It omits cost/performance characteristics on large models and any permission requirements for reading a .pbip directory.

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

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

Front-loaded with the core purpose, then a scannable bulleted usage block, then Args/Returns. The closing paragraph on why the answer must be a calculation group/helper table/rewrite is slightly discursive but earns its place by managing expectations about output.

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?

Even though an output schema exists (so return values needn't be spelled out), the description still summarizes the returned grouping structure usefully. Combined with coverage of all three args and the read-only caveat, an agent has what it needs; the only shortfall is no guidance on model size limits or failure modes.

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

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

Schema coverage is 0%, so the description must compensate and largely does: pbip_path is defined as the root .pbip directory, table as a scoping filter, and min_group_size as the sharing threshold with 'two is the minimum' clarifying the floor. Minor gap: pbip_path doesn't clarify whether relative or absolute paths are accepted.

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?

Specific verb (find duplicated logic) plus a precisely scoped resource (measures in a semantic model), with concrete examples of what 'duplication' means (copy-pasted, same computation, differ only by a number/column). It doesn't explicitly name the neighboring tools it should be distinguished from (e.g. refactor_to_calculation_groups, simplify_dax_measure), so sibling separation is inferential 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?

A bulleted 'use this tool when the user asks to' block gives three concrete triggering intents, which is well above implied usage. It also implicitly separates itself from the applier by stating 'does not apply the abstraction', but never names the alternative tool or states when NOT to use this one.

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

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

With no annotations, the description carries the full burden and mostly succeeds: it discloses that dry_run defaults to True and only dry_run=False persists, that fail_on_severity gates creation, that runtime_check needs an active engine, that lint findings are returned, and that measure_writer is not reachable from an MCP client. It does not state required permissions or whether an existing measure is overwritten.

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

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

Front-loaded with purpose, then usage, then args, then returns – a clean hierarchy. The Args block is long but earns its place given 0% schema coverage; the only mild redundancy is restating parameter names alongside the schema.

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 11 parameters, a default-on dry-run safety gate, and a mutation target, the description covers usage, all arguments, and the return payload (success status, lint findings, modified file paths). It omits error/failure modes and permission prerequisites, which are the only remaining gaps for a write 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%, yet the description documents every meaningful parameter with type-appropriate examples ('$#,##0.00', 'DIVIDE([Total Sales], [Units], 0)') and clarifies the enum values for fail_on_severity. It fully compensates for the schema gap, including flagging the one parameter an agent cannot 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?

States a specific verb and resource ('Add a DAX measure to a semantic model') plus the differentiator ('with automated linting and validation'). No sibling tool in the list adds measures, so the resource boundary is 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?

Explicit 'Use this tool when the user asks to:' section gives three concrete trigger conditions, including dry-running before committing. It stops short of naming when NOT to use it or which sibling to prefer (e.g. execute_dax_query for querying, run_dax_regression for testing), so it is clear context without 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?

With no annotations, the description carries the full burden and does well: it discloses automatic rollback on step failure, that dry_run defaults to True (safe-by-default), and that declining a step or lacking an interactive client halts execution and reports remaining steps as not run. It omits auth/permission requirements and what state rollback restores.

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?

Well front-loaded: purpose first, then usage, then Args and Returns. The Returns section is largely redundant given an output schema exists, which is the only wasted content.

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

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

For a 3-parameter execution tool with no annotations, the definition covers purpose, every parameter's semantics and defaults, failure/rollback behavior, and interactive-client edge cases. An agent has everything needed 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, and it does: plan_id is tied to plan_change, dry_run is documented with its default and the instruction to pass False explicitly for real application, and confirm_each_step's interactive and no-client behavior is spelled out.

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

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

States a specific verb+resource ('Execute an approved plan') and adds a distinctive behavioral trait ('automatic rollback on step failure'). It implicitly and correctly positions itself downstream of plan_change, letting an agent distinguish it from the plan-creation sibling.

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 when-to-use bullets (execute an approved plan, run dry-run, approve each step) and names plan_change as the origin of the required plan_id. It never states when NOT to use it or what alternative to pick if no approved plan exists, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that visuals are modified (a 'modified visual count' is returned) and that a WCAG re-audit occurs, which signals mutation. However, it says nothing about permissions required, whether changes to the .pbip directory are reversible, idempotency, or rate/scope limits.

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

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

Front-loaded with the core action, then clearly sectioned into usage triggers, args, and returns. Slightly padded by the repeated 'Use this tool when the user asks to' phrasing, but every line carries usable information.

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

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

For a multi-action mutation tool, the description covers purpose, triggers, all four parameters, and (redundantly, since an output schema exists) return shape. The remaining gap is behavioral: side effects on the .pbip directory and whether the operation is safe to re-run are not addressed, which matters more here because no annotations are supplied.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: it documents all four parameters (pbip_path, palette with example values, auto_backfill_alt_text, alt_text_template). It gives the meaning and intent of each, though it omits the exact enum constraint for palette and the default values that the schema supplies.

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 three concrete actions (apply a colorblind-safe theme, backfill alt text, re-audit WCAG) on a specific artifact type, so the agent knows exactly what it does. It is clear but never explicitly differentiates itself from sibling audit tools like audit_report_ux_and_storytelling or audit_model_and_report, which is what a 5 would require.

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 'Use this tool when the user asks to:' block gives three explicit trigger scenarios (WCAG compliance, colorblind-safe palette, alt-text generation), which is strong positive guidance. It stops short of naming when-not to use it or pointing to an alternative sibling, so it does not reach a 5.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the audit is composite and that bpa/dax_lint/accessibility/naming are individually switchable, and that it returns a score/pass-fail with categorized findings. It does not state whether the operation is read-only, what permissions or runtime cost it incurs, or how the sub-checks interact.

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

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

Front-loaded with the core purpose, then structured Usage/Args/Returns sections with no filler. The Returns block is partly redundant given an output schema exists, but the overall structure is efficient and scannable.

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 7-parameter, no-annotation tool with an output schema, it covers purpose, triggers, and every argument. The gaps are minor: no read-only/side-effect note and no interaction guidance among the boolean toggles.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all seven parameters are named and explained, including the bpa_ruleset enum values (default/strict/lenient) and the optional dax_measures_json. It omits declared defaults and how dax_lint interacts with dax_measures_json, so not a full 5.

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

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

States a specific verb (audit) and resource (Power BI PBIP project / semantic model / report) and enumerates the concrete dimensions checked: BPA rules, DAX quality, naming, WCAG accessibility. It does not explicitly differentiate itself from close siblings like audit_report_ux_and_storytelling or powerbi_health, 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?

Provides a clear 'Use this tool when the user asks to:' trigger list covering audit, BPA/DAX/naming, and WCAG validation, which gives an agent solid routing signal. However, it names no alternatives or when-not-to-use conditions against the many overlapping 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 supplied, so the description carries the full behavioral burden. It usefully discloses scope behavior ('audits all pages if omitted') and the return shape (0-100 score, category breakdowns, suggestions), but never states that this is a read-only, non-destructive local analysis with no writes to the .pbip, nor any permission or performance notes. Adequate but with a clear gap given zero annotation coverage.

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?

Purpose is front-loaded in one line, followed by purpose-built trigger bullets and an Args/Returns block. Every section earns its place, though the Args and Returns lists restate information the schema/output schema already carry, adding some redundancy.

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

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

For a 4-parameter, single-required read/analysis tool with an output schema, the description covers what it does, when to use it, the meaning of each parameter, and the shape of the result. Given the output schema exists, the Returns summary is a bonus rather than a necessity; the only real gap is the absence of any behavioral/safety note.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all four parameters are documented in the Args block, including that page_name is optional and defaults to auditing all pages and that strictness/audience_assumed take named categorical values. It stops short of enumerating the allowed values as a closed set (schema declares no enums) or giving syntax examples for pbip_path.

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 (Evaluate/Audit) and concrete resources (report storytelling, visual hierarchy, cognitive load, UX design), which is far more informative than the tool name alone. The 'when the user asks to' bullets further scope it to design-quality and dashboard-best-practice auditing, distinguishing it from siblings such as audit_model_and_report (model+report) and design_report_page_from_requirements (generation).

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

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

It gives explicit trigger conditions ('Audit report design quality, narrative flow, or visual hierarchy' and 'Check if a report follows dashboard best practices for a specific audience'), so an agent knows when to reach for it. It does not name an alternative or exclusion (e.g., when to prefer audit_model_and_report or optimize_report_performance instead), which keeps it short of a 5.

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

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

With no annotations, the description carries the full burden. It usefully discloses that dry_run defaults to True and returns committed items, commit SHA, and repo status, but says nothing about Git authentication/credentials, whether existing files in the target repo are overwritten or staged, or whether the operation 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?

Well front-loaded: purpose sentence first, then trigger bullets, then Args, then Returns. The trigger bullets partially restate the opening sentence, which is slight redundancy, but nothing is padded or wasted.

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

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

For a six-parameter mutation tool with an output schema already present, the description covers purpose, triggers, parameters, and a return summary. The main remaining gap is operational prerequisites (Git auth/permissions and repo state preconditions), which an agent would want before committing.

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 Args block is the only parameter documentation and it covers all six parameters, including the important dry_run semantic ('inspect items without creating git commits'). It remains thin on defaults (branch, commit_message) and on what 'item IDs' in exclude_items actually refer to.

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 pair (export and commit), the resource (Fabric workspace), and the destination (local Git repository). The 'into a local Git repository' direction cleanly separates it from the sibling sync_git_to_workspace, which flows the other way.

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

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

It gives an explicit 'Use this tool when the user asks to' block with two concrete trigger scenarios (backup/version-control a workspace, snapshot reports and semantic models into PBIP). It stops short of naming when NOT to use it or pointing to the reverse-direction sibling, so it is clear context without 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?

With no annotations, the description carries the burden well: it discloses that authentication mode falls back to the PBI_AUTH_MODE env var and then to "interactive", that tenant_id is mandatory for service-principal auth, and that the call establishes a session that returns engines_available and diagnostic warnings. It does not address session lifetime, idempotency of repeated connects, or whether the operation mutates any remote state, which keeps it below 5.

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

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

Front-loaded purpose sentence followed by tight trigger bullets, Args, and Returns sections — easy to scan. The Returns block duplicates information already available in the output schema, so it doesn't fully earn its space, but overall there is little waste.

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

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

For a 4-parameter session-bootstrap tool with an output schema present, nearly everything an agent needs is stated: target types, auth paths, required env fallbacks, and conditional requirements. The single unresolved point is how target_ref should be supplied for pbi_desktop, a gap that could cause a malformed first call.

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 largely does: it enumerates the allowed target_type values, explains target_ref differs by type (path for PBIP/PBIX, workspace UUID for Fabric), and gives auth_mode options plus default precedence. The only gap is that target_ref is left unexplained for pbi_desktop, which is precisely the kind of ambiguity an agent would hit at call time.

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

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

The description opens with a specific verb+resource pair ("Connect to a Power BI target and initialize an orchestrator session") and then enumerates the four target kinds it accepts. No sibling in the list performs connection/session setup, so the tool is unambiguously distinguishable.

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?

An explicit "Use this tool when the user asks to" block lists concrete trigger scenarios (Desktop session, Fabric workspace, PBIP folder, PBIX file, interactive inspect/modify). It stops short of naming exclusions or pointing to a follow-on sibling, but the positive context is clear and actionable.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses what gets generated (pages, cards, charts, theme) and the return shape, but says nothing about whether an existing .Report folder is overwritten, whether the operation is idempotent, or what permissions/paths are required for a filesystem-writing 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?

Front-loaded purpose sentence followed by a scannable use-case list and Args/Returns blocks. Slightly verbose in restating defaults that already live in the schema, but nothing is wasted or buried.

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?

An output schema exists, so the Returns block is a bonus rather than a necessity, and the generation behavior and parameters are well covered. The remaining gap is mutation semantics (overwrite/idempotency) for a tool that writes report scaffolding with no annotations to fall back on.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: all six parameters (pbip_path, page_name, visual_count, theme, include_card, inspector) are explained with intent and stated defaults. The one weak spot is 'inspector', described only as 'Optional model inspector' with no indication of what object or behavior is expected.

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

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

States a specific verb (scaffold) and artifact (.Report folder plus layout) derived from an existing semantic model, which clearly separates it from model-creation siblings like create_semantic_model_from_schema. It does not explicitly distinguish itself from the arguably overlapping design_report_page_from_requirements, so it falls 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 'Use this tool when the user asks to' list gives concrete trigger conditions (create a new .Report folder for an existing dataset, generate starter pages). However, it names no alternatives and gives no when-not guidance, e.g. versus design_report_page_from_requirements or edit_report_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?

With no annotations, the description carries the full behavioral burden. It does disclose that dry_run validates without writing files and that output lands as a .pbip project on disk, but it says nothing about overwrite behavior when output_pbip_path already contains a project, required permissions, or the odd empty-string default of output_pbip_path (where does it write then?).

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

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

Front-loaded purpose sentence, then a bulleted trigger list, then Args/Returns. Given 0% schema coverage the Args block earns its space; nothing is redundant filler.

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

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

An output schema exists, so the Returns text is a redundant but harmless convenience. The description is nearly complete for a file-writing generator: params are fully explained. The residual gap is mutation safety semantics (overwrite/merge behavior) which is material for a tool that writes a project directory.

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%, but the description compensates by documenting all four parameters: spec_yaml, spec_json (string or structured object), output_pbip_path, and dry_run semantics. It omits the key relationship between spec_yaml and spec_json (mutual exclusivity / precedence) and does not flag that dry_run defaults to true, leaving the agent to infer it from 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?

States a specific verb and resource ('Generate a TMDL semantic model and PBIP project') plus the input modality ('from a declarative schema spec'). The 'from scratch' framing distinguishes it from sibling mutation tools like refactor_to_calculation_groups or create_report_from_dataset, which operate on existing artifacts.

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

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

Gives clear when-to-use triggers ('Create, scaffold, or generate a new Power BI semantic model from scratch') and enumerates the declarative constructs it handles. It never names an alternative tool or states when NOT to use it (e.g., modifying an existing model), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the burden and does well: it explains that dry_run=True evaluates gates and reports planned operations without calling Fabric APIs, dry_run=False actually publishes, and mock=True simulates deployment. It also documents auth fallback to PBI_AUTH_MODE and return contents, though it does not state required permissions or irreversible side effects of publishing.

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

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

The description is front-loaded with purpose and usage triggers, then uses a clean Args list and Returns summary. Every sentence serves a purpose, and the critical dry_run default is called out clearly without excess prose.

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

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

For a 10-parameter mutation tool with no annotations and an output schema, the description is complete enough: it covers when to use it, what each parameter means, the safety-relevant dry_run/mock behavior, authentication options, and what the result contains. An agent can invoke this correctly without additional 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, and it does: every parameter is explained in Args, including default behaviors (dry_run=True, refresh_daily_hour=6), accepted gate profiles, auth mode fallback, and the dual list/JSON-string nature of findings_json. This adds substantial meaning beyond bare schema types.

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

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

The description opens with a specific verb and resource: deploying a PBIP project to a Fabric/Power BI workspace with pre-deploy gates. It clearly distinguishes this from generic publishing or refresh tools and names the artifact type (.pbip), target platform, and gate behavior.

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

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

It provides explicit triggers: deploy/publish/release a .pbip project, run pre-deployment quality gates before publishing, and schedule daily refresh. However, it does not distinguish this from the sibling pre_deploy_check tool or say when to use this versus that or sync_git_to_workspace, leaving a small ambiguity.

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

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

With no annotations, the description carries the full behavioral burden for what is clearly a mutating, file-writing operation. It never states whether an existing page of the same name is overwritten, whether the pbip is modified on disk, what permissions or prerequisites apply, or whether the operation is reversible. The Returns line is the only behavioral disclosure and it duplicates 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?

Front-loaded purpose sentence followed by tight, scannable usage bullets and a compact args block. The Returns section is redundant given an output schema exists and could be dropped, but overall there is little waste.

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 six-parameter, zero-coverage-schema, unannotated mutation tool, the parameter documentation is adequate and the output schema covers return values. What is missing is the mutation/side-effect profile (overwrite behavior, disk writes) that the absent annotations leave entirely to the description.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does: all six parameters are named with meaning, including defaults for page_name and palette, the accepted audience values, and that inspector is an optional model inspector for schema context. Remaining gap is format detail for pbip_path and the inspector object.

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

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

The opening sentence gives a precise verb and resource: synthesize a complete PBIR report page layout from a natural-language brief. That is far more specific than sibling names like create_report_from_dataset or select_visuals_for_kpis, but the description never explicitly contrasts itself with those siblings, so an agent must infer the boundary.

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

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

The 'Use this tool when the user asks to' block gives three concrete triggering scenarios (new page from business requirements, auto visual selection/sizing, applying color schemes and hierarchy). That is clear usage context, but there is no when-not guidance and no named alternative for cases where an existing page should be edited (e.g. edit_report_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?

With no annotations, the description carries the full burden. It does convey that this is a passive read/compare operation and sketches the return shape (added/removed/modified buckets), which is useful. It says nothing about prerequisites such as whether the PBIP paths must exist locally, whether a connection via connect_target is needed, cost on large models, or error behavior for invalid paths.

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

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

Front-loaded with the one-line purpose, then usage triggers, then args, then returns — an agent can stop reading after line one. The Returns block is somewhat redundant given that an output schema exists, but it is short enough not to be wasteful.

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

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

For a two-parameter comparison tool with an output schema and no annotations, the description covers purpose, triggers, parameter meanings, and result categories. The main missing piece is prerequisite/setup context relative to siblings like connect_target, which an agent would have to infer.

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 does, naming both params and defining role and type ('before: Path to the baseline PBIP directory', 'after: Path to the target PBIP directory'). It does not specify path format expectations (absolute vs. relative) or whether the directories must already be materialized, leaving a small 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?

States a specific verb and resource: 'Compare two semantic models and report structural differences', then enumerates exactly which artifact classes (tables, columns, measures, relationships) are diffed. No sibling tool does version-to-version comparison, so an agent can route here unambiguously.

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

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

Explicit trigger conditions are given: comparing two versions of a Power BI model/PBIP directory, or seeing what changed between branches or releases. It stops short of naming alternatives (e.g., audit_model_and_report or plan_change) or stating when not to use it, so it lands just below the top mark.

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 discloses the return shape (success status, changes applied, page path), which is useful, but says nothing about permissions required, reversibility of edits, validation/error behavior, or what happens to fields not specified. Adequate but incomplete for a mutation tool with zero annotation coverage.

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

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

Front-loads the core purpose, then offers a tight when-to-use block, an Args list, and a Returns line. Given nine undocumented parameters, the length is justified and every line 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?

An output schema exists so return values need not be spelled out, yet the description still gives a concise summary. Combined with full parameter coverage, an agent has everything needed to call this tool correctly.

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

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

With 0% schema description coverage, the description fully compensates by documenting all nine args: root .pbip path, page name, visual ID, new visual type with examples ('barChart', 'lineChart', 'card'), and the fields/format/position JSON blobs including accepted shapes (dict or JSON string; x/y/width/height). This adds substantial meaning the bare schema lacks.

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

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

States a specific verb (Modify) and resource (a visualContainer in a PBIR report page) and enumerates the scope (type, fields, formatting, layout). An agent can immediately see this is the visual-editing tool, though it doesn't explicitly name which siblings it is not (e.g. design_report_page_from_requirements).

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 an explicit 'Use this tool when the user asks to:' block with concrete triggers (edit/reformat/resize a chart, change fields/bindings/alt text/visibility). Clear usage context, but no explicit when-not or named alternative among the many sibling tools.

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

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

With no annotations present, the description carries the full burden and does substantially well: it discloses both auth flows ('interactive' browser login vs 'service_principal'), the tenant/client credentials the latter requires, the impersonation mechanism for RLS testing, and a hard row ceiling of 10000 with an explicit rationale (preventing bulk extraction into model context). It never explicitly states the operation is read-only/non-mutating or what workspace permissions are needed, which is the remaining 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?

Front-loaded with a one-line purpose, then the when-to-use list, then a param block — logical and scannable. The closing 'Returns' sentence partly restates a shape already conveyed by the output schema, and the Args block is long, though that length is justified given 0% schema coverage.

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 9-parameter, auth-sensitive tool with no annotations, this covers purpose, selection criteria, every parameter, credential requirements, and safety limits on row volume. Missing elements are secondary: error/failure behavior, workspace permission prerequisites, and guidance relative to the DAX-related siblings; return values are already covered by the output schema.

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

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

Schema description coverage is 0%, so the description must compensate entirely — and it does, documenting all nine parameters including the easily-missed testing-only fabric_client. It adds meaning the schema lacks: the two valid values for auth_mode (which has no enum in the schema), the dependency of tenant_id on service_principal mode, the default and 10000 ceiling for max_rows, and concrete DAX syntax examples for dax_query.

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

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

States a specific verb and resource: 'Execute a DAX query against a published Power BI semantic model / Fabric dataset.' That is unambiguous and far beyond the bare tool name. It does not, however, distinguish itself from the sibling run_dax_regression, which an agent could plausibly confuse with 'run or test a DAX query'.

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 supplies an explicit 'Use this tool when the user asks to:' list covering data inspection, measure/KPI verification, and RLS testing via impersonation — clear positive selection criteria. It stops short of stating when NOT to use it or naming which sibling to use instead (e.g. run_dax_regression for suites).

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 burden. It discloses that output_path optionally saves the Markdown (a file-write side effect) and describes the return payload, but says nothing about permissions, cost, or whether the operation touches the model. Adequate but thin for a tool with zero annotation coverage.

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

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

Front-loaded one-line purpose followed by scannable trigger bullets and Args/Returns sections. The Returns block slightly duplicates the output schema, but overall it is efficient and well-organized.

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 3-parameter documentation generator with an output schema present, the description covers purpose, triggers, parameters, and return shape. Nothing essential to a correct invocation is missing, though the inspector parameter's nature remains unspecified.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents all three parameters: pbip_path as 'Path to the .pbip directory', output_path as an optional save path, and inspector as an optional model inspector. Only 'inspector' is somewhat circular/tautological, so a 4 rather than 5.

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

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

States a specific verb+resource (generate Markdown documentation and Mermaid ER diagram) for a semantic model, and the trigger bullets make the output artifacts concrete. It is clearly distinguishable from siblings like audit_model_and_report or create_report_from_dataset.

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 an explicit 'Use this tool when the user asks to' list with three concrete trigger scenarios (document a dataset, generate a data dictionary, create a Mermaid ER diagram). It gives clear positive context but no when-not conditions or named 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?

No annotations are provided, so the description carries full behavioral burden. 'Analyze' implies a read-only operation and the Returns block discloses a score/load-time/recommendations shape, but it never states prerequisites (e.g. that the .pbip must exist/be connected), that nothing is mutated, or any cost/latency characteristics of the analysis.

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

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

Front-loaded with the core purpose, then a scannable when-to-use list and short Args/Returns blocks. Minor redundancy in the Returns section given an output schema already exists, but nothing is wasted.

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

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

For a 2-parameter read-only analysis tool, the description covers purpose, triggers, both arguments, and the return shape. The Returns block partially duplicates the output schema, and no sibling routing is offered, but an agent has enough to call 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 coverage is 0%, so the description must compensate, and it does: pbip_path is explained as the .pbip directory path and target_load_ms as desired max page load latency with a 5000 ms default. Both parameters gain meaning beyond the bare schema titles.

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

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

States a specific verb (Analyze) plus resource (PBIR report pages) and scope (visual performance bottlenecks and anti-patterns). This is distinct from UX-focused siblings like audit_report_ux_and_storytelling, though the description never names a sibling to reinforce the boundary.

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

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

An explicit 'Use this tool when the user asks to...' block with two concrete triggers (slow-loading pages, excessive visual density/expensive custom visuals). It gives clear positive context but no exclusions or named alternatives against siblings such as audit_model_and_report.

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 supplied, so the description carries the full disclosure burden. It usefully flags rollback/atomicity intent and points at options like auto_rollback and dry_run_first, but never states the critical fact that this only produces a plan and does not mutate the model (unlike apply_plan), nor any auth/prerequisite 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?

Front-loaded one-line summary, then a scannable usage list and short Args/Returns blocks. Slightly verbose in the Returns section (an output schema already exists), but every other sentence earns its place.

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

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

For a 2-parameter tool with an output schema, the description covers intent templates, option shapes, and the return fields the agent needs to chain into apply_plan. The main omission is the non-mutating/side-effect guarantee and any connectivity prerequisite.

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 schema declares intent as a bare string with no enum, so the description is the only source of the four valid template values and the per-template options shape (old_path, new_path, scope). It adds substantial meaning beyond the schema, though options remains loosely specified.

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

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

States a specific verb and artifact ('Create a versionable, multi-step execution plan') plus its source ('from an intent template'). This clearly separates it from the sibling apply_plan, which presumably executes what this produces, without needing to open either schema.

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

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

The description gives an explicit 'Use this tool when the user asks to' list covering complex/risky operations, safe_rename, and audit/deploy/DAX runs. It provides clear positive context but names no alternatives (e.g. apply_plan for execution) or when-not-to-use conditions, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Diagnose' plus the enumerated returns (system status, engine availability matrix, active store counts, remediation advice) implies a read-only operation, but the description never explicitly states that it has no side effects or what permissions it needs. The Returns section is largely redundant with the declared 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?

Well front-loaded: purpose first, then use-when bullets, then args, then returns. The Args and Returns blocks are cleanly separated, but the Returns block duplicates the output schema and dilutes the otherwise tight structure.

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

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

For a one-parameter read-only diagnostic with an output schema, the description covers purpose, triggers, parameter meaning, and return shape. The remaining gap is an explicit statement of read-only/non-mutating behavior and any auth or environment prerequisites for the engines it inspects.

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 brief 'Whether to return full diagnostic info and remediation tips for each engine' is the only semantic explanation of the sole parameter, and it usefully clarifies the true/false tradeoff. It adequately compensates for the schema gap, though it could say more about verbosity/cost implications.

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

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

The description opens with a specific verb+resource: 'Diagnose orchestrator health, detected modeling engines, and storage readiness.' This is a unique diagnostic function among the siblings (all of which are model/report operations), so an agent can immediately distinguish it without inspecting any schema.

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

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

It gives explicit trigger conditions ('Use this tool when the user asks to: check if the orchestrator is running, see which engines are installed, get setup instructions'), which is unusually clear for context selection. It stops short of a 5 only because it names no exclusions, though no sibling offers an overlapping capability that would need routing away from.

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 behavioral burden. It discloses the return payload (gate decision, blocking findings, warnings), which is useful, but says nothing about side effects, permissions, or whether the check is purely read-only or has any deployment impact.

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

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

The description is front-loaded with the core purpose, then uses clean labeled sections (usage bullets, Args, Returns) that make it easy to scan. It is slightly longer than strictly necessary given the output schema, but nothing is wasteful.

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

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

For a two-parameter, zero-required, non-destructive evaluation tool, both parameters are described and the return shape is sketched (even though a real output schema exists). The only gap is the absence of any behavioral/permission context, which is minor for this kind of gate-check tool.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it documents both parameters, clarifying that findings_json accepts a list or JSON string, and enumerating the 'strict'/'standard'/'lenient' profile values that the schema leaves unspecified.

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

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

The description states a specific verb and resource ('Evaluate audit findings against a pre-deployment quality gate profile'), which is clear and actionable. It is reasonably distinguishable from siblings like audit_model_and_report, though it never explicitly contrasts itself with any of 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?

It gives explicit 'use this tool when the user asks to' guidance with two concrete scenarios, which is stronger than most. However, it names no alternatives and gives no when-not-to-use conditions, so it falls short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does so: it discloses that dry_run defaults to True, that gates/stage validation run without promoting in that mode, and explicitly warns that dry_run=False 'moves live artifacts between stages.' That is precisely the destructive-path disclosure an agent needs before calling 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?

Front-loaded purpose sentence followed by a scannable when-to-use list and an Args block. Every line carries information; there is no filler or repetition of the title.

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?

An output schema exists so the Returns block is technically redundant, though harmless and mildly useful. For a 5-param mutation tool with no annotations, the definition covers purpose, usage, param semantics and the dangerous default; only auth/permission prerequisites are absent.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: every one of the 5 params is explained — UUID format for pipeline_id, allowed stage values for source/target, the omitted=promote-all semantics of items, and the validate-vs-execute semantics of dry_run. This adds real meaning beyond the bare schema.

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

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

States a specific verb ('Promote') and resource ('artifacts across Microsoft Fabric Deployment Pipeline stages'), which separates it from generic deploy/apply siblings. It does not explicitly name which sibling to prefer (e.g. deploy_to_workspace vs apply_plan), so it stops short of full sibling 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 'Use this tool when the user asks to' bullets give clear triggering conditions (stage-to-stage promotion, pre-promotion gate checks). It never states when NOT to use it or which sibling handles the adjacent cases, so the routing half of the guidance is missing.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral split: auto_apply=True writes immediately while False returns a proposed plan, and preserve_originals controls whether source measures survive. It does not state reversibility, permissions, or risk of modifying the model, leaving some mutation-safety 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?

Front-loaded one-line purpose followed by scannable trigger list and Args/Returns blocks. The Returns block largely restates what the existing output schema already provides, so it is slightly redundant but not bloated.

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

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

For a mutation tool with no annotations and seven parameters, the definition covers purpose, triggers, every argument, and the plan-vs-apply distinction, and an output schema exists so return shape need not be re-explained. Missing only safety/reversibility context that annotations would normally supply.

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 documents all seven parameters. Most add real meaning (auto_apply, preserve_originals, reconcile_strategy), though 'inspector: Optional model inspector' and 'measure_writer: Optional measure writer callable' are near-tautological and reconcile_strategy never explains strict vs lenient.

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

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

States a specific verb ('consolidate') and resource ('repetitive measures ... into calculation groups') with a concrete example (YTD, QTD, PY), so the agent knows exactly what the tool does. It does not name or distinguish itself from any sibling, which keeps it just 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?

Gives explicit when-to-use triggers ('when the user asks to refactor or clean up redundant DAX measures', 'reduce model complexity'). There is no when-not guidance or named alternative (e.g. add_measure_with_validation), so it is clear but not exhaustive.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses auth modes, a return shape, and the meaning of executed=False, but it does not state whether the operation is read-only, what permissions are required, or whether it has any side effects on the workspace or baseline file.

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

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

The description is front-loaded with a one-sentence purpose, followed by focused usage bullets, grouped Args, and a Returns note. It is appropriately sized for nine parameters and does not waste space on repeated schema information.

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

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

The description covers the purpose, use cases, all nine parameters, auth choices, and return behavior, which is strong for a no-annotation tool. It is slightly incomplete because it does not clarify side-effect/read-only behavior or the baseline file structure expected by the 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% across nine parameters, and the description compensates by explaining every one: baseline_path, queries_json, tolerance_pct with default, workspace_id, dataset_id, auth_mode values, tenant_id, client_id, and fabric_client. This adds substantial meaning beyond the bare schema types.

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 states a specific verb and resource: run DAX queries against a baseline and assert regression tolerance. The usage bullets clarify that it is for baseline comparison, consistency verification, and CI/CD tolerance checks, which distinguishes it from the generic sibling execute_dax_query.

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 when-to-use guidance with three concrete scenarios: consistency verification, comparison against a golden baseline, and CI/CD tolerance checking. It does not explicitly state when not to use it or name execute_dax_query as the alternative for ad hoc DAX execution.

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, so the description carries the full burden and does so well: it discloses that dry_run defaults to True and no refresh happens unless explicitly set False, that wait polls until completion with a timeout_s default of 1800, and that auth_mode resolves through PBI_AUTH_MODE to 'interactive'. That is exactly the safety and long-running-operation context an agent needs before invoking a mutation.

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 purpose sentence and the 'use when' list are front-loaded, and each Args entry earns its place given zero schema coverage. It is slightly long due to docstring-style formatting, and the Returns block is partly redundant with the existing output schema, but nothing is padded.

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 9-parameter mutation tool with no annotations, the description covers trigger semantics, polling behavior, auth resolution, the safe dry-run default, and return contents. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, and the description compensates for all nine parameters: UUID formats for workspace_id/dataset_id, the enumerated refresh_type values, the semantics of wait and timeout_s, the auth_mode fallback chain, and the critical dry_run default behavior. This adds substantial meaning the schema alone cannot convey.

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 set (trigger, monitor, wait) and a specific resource (Power BI dataset refresh), which maps directly to a distinct capability none of the siblings (deploy_to_workspace, execute_dax_query, pre_deploy_check) cover. An agent can identify this tool's job without opening the schema.

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

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

It gives an explicit 'Use this tool when the user asks to:' list covering refresh, status checks, and refresh type selection, which is clear positive routing. It does not state when NOT to use it or name an alternative for adjacent needs (e.g., health checks vs. actual refresh), so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden. It does disclose that images are written to output_dir (a filesystem side effect), that wait_ms controls visual rendering, and that results include warnings and rendering metadata. However it says nothing about required permissions, whether a live connection (connect_target) must precede it, or how failures are surfaced.

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

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

Front-loaded purpose sentence, then scannable use-case bullets, Args, and Returns. Given 0% schema coverage, the Args block earns its space rather than duplicating structured data.

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 rendering tool with a large sibling set, the description covers purpose, invocation context, args, and return shape (even though an output schema also exists). The one real gap is prerequisite state — whether the report must be connected/open first — which the sibling connect_target implies but the description never states.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: all six parameters are named with meaning, and it supplies value sets the schema lacks (format: png/svg/pdf; resolution: desktop/mobile/tablet; pages as an optional page-name list). It stops short of 5 only because units/defaults and interactions (e.g. format vs resolution) are not clarified.

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

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

States a specific verb (capture screenshots or structural wireframes) against a specific resource (Power BI report pages). No sibling tool does capture/snapshot work, so an agent can select it without ambiguity.

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 when-to-use triggers ('visually inspect or capture report pages for reviews or regression diffs', 'generate SVG wireframes or image snapshots of PBIR layouts'). No when-not conditions or named alternatives (e.g. audit_report_ux_and_storytelling), so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Recommend' implies a non-mutating helper, and the Returns section sketches the output shape, but it never states side-effect freedom, cost, or whether it requires a live model connection. Adequate but with clear gaps for a zero-annotation 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?

Structurally front-loaded with the purpose sentence followed by usage bullets and args. The Returns section partly duplicates the existing output schema, which is mild redundancy, but overall the text is tight and skimmable.

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 four-parameter, zero-coverage, zero-annotation tool, the description covers purpose, triggers, and every argument. Since an output schema exists, the Returns prose is a bonus rather than a requirement, and only the absence of behavioral caveats keeps it from a 5.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it documents all four parameters, enumerates the audience personas ('executive', 'analytical', 'operational'), and explains inspector as supplying column cardinality/schema info. This is well beyond what the bare schema conveys.

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

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

The description opens with a specific verb and resource: 'Recommend optimal visual types and chart configurations for given KPIs.' An agent can tell this is a recommendation/design aid rather than a mutation. It does not explicitly differentiate itself from siblings like edit_report_visual or design_report_page_from_requirements, which keeps it from 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?

It provides explicit trigger conditions via three 'Use this tool when the user asks to:' bullets covering chart selection, audience tailoring, and primary/alternative suggestions. There is no statement of when NOT to use it or which sibling to prefer instead, 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?

With no annotations, the description carries the full behavioral burden, and it does add real value: dry_run is explained as 'validate permissions without applying labels' and redact_names as log redaction. However, it omits whether labels are reversible, what permissions are actually required (admin_scopes is mentioned only as an arg), and whether dry_run defaults to True — schema shows default true, meaning an agent could believe labels were applied when nothing happened.

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?

Purpose and trigger conditions are front-loaded, then Args/Returns blocks; nothing is wasted. The Args section inherently restates parameter names, and the Returns block is partly redundant given an output schema exists, but the utility description itself is tight.

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?

An output schema exists so return-value detail is not required, and the description still summarizes the shape (updated items, failed items, compliance status). For a 6-parameter mutation tool with zero annotations, it covers intent, params, dry-run safety, and error surface adequately; the remaining gap is permission/irreversibility 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% (only titles like 'Label Id'), so the description must compensate, and it documents all six parameters with meaning beyond the schema: item dict shape with a concrete example, label_id as a Purview GUID, label_name as display name, admin_scopes as optional authorization scopes, and the semantics of redact_names and dry_run. It does not list valid label_name values or item type enumerations, which keeps it at 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 first sentence states a specific verb and resource ('Apply Microsoft Purview information protection sensitivity labels to items'), which is unambiguous and actionable. It does not name or contrast with any sibling tool, but no sibling in the list performs label application, 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?

'Use this tool when the user asks to: classify or protect Power BI items... / set Purview sensitivity labels' gives explicit trigger conditions tied to user intent. It stops short of stating when NOT to use it or pointing to an alternative for adjacent tasks (e.g. RLS/roles via setup_rls_and_roles), so it earns 4 rather than 5.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that dry_run validates without writing to disk and that rollback_on_test_failure can revert changes, which are important safety semantics for a mutating setup tool. It still omits permissions, overwrite behavior, and broader 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 front-loaded with purpose, then usage, args, and returns in a clear structure. The Returns section is somewhat redundant because an output schema exists, but the overall text remains efficient and easy to scan.

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

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

For a five-parameter RLS setup tool with no annotations and an output schema, the description covers purpose, usage, arguments, and return shape. It is nearly complete, though it does not explain the expected schema of spec_yaml/spec_json beyond high-level contents, which would help an agent construct the call.

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%, but the description documents all five parameters: target, spec_yaml, spec_json, dry_run, and rollback_on_test_failure. It adds substantive meaning beyond the bare schema titles, including the YAML/JSON spec contents and the write/validation behavior of the boolean flags.

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

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

The description states a specific verb and resource: 'Configure Row-Level Security (RLS) roles and validation rules in a TMDL model.' That is distinguishable from siblings such as set_sensitivity_labels or apply_theme_and_accessibility_rules, which address different Power BI concerns.

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

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

It gives explicit when-to-use guidance via bulleted user intents: setting up/adding/configuring RLS roles and DAX table filter expressions, plus testing and validating security rules. It does not name alternatives or exclusion conditions, so it stops short of the top score.

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

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

With no annotations available, the description carries the full burden and does so well: it states the tool writes nothing, that equivalence is structural rather than data-evaluated, that unparseable input returns unchanged with a reason, and what apply_lint adds. These are exactly the safety and behavior traits an agent needs before calling.

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

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

Front-loaded with a one-line purpose followed by scannable intent bullets, and the Args section is tight. The Returns paragraph is somewhat long and partly restates what an output schema would show, which costs a point but not much.

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 optional parameters, no annotations, and a moderately complex behavior (structural rewriting, lint comparison), the description covers selection, exclusivity, behavior, and the write-nothing guarantee. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for all five parameters: expression vs. pbip_path exclusivity, measure/all_measures requiring pbip_path, and apply_lint's before/after lint verdict semantics. This is meaning the schema alone does not convey.

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

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

The description gives a specific verb (rewrite/simplify) applied to a specific resource (a DAX expression/measure), and the bullet list of user intents ('shorten a DAX measure', 'find measures written the long way', 'replace a hand-rolled blank check') makes it distinguishable from near-siblings like abstract_measures or abbreviate_names.

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

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

It explicitly enumerates when to use the tool (three concrete user asks), states the mutual-exclusion rule between expression and pbip_path, states the prerequisite that measure/all_measures require pbip_path, and names add_measure_with_validation as the follow-up path for actually applying a result.

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 does disclose that dry_run calculates changes without publishing and that conflict_resolution governs conflict handling, and it outlines the return shape. However, it never states that publishing overwrites existing workspace items, what permissions are required, or whether the operation is reversible, which are the key behavioral facts for a mutating deploy 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?

Front-loaded with a one-line purpose, then scannable 'when to use', Args, and Returns sections. Well organized and mostly earning its space, though the Returns block is largely redundant given that an output schema exists.

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

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

For a mutating deploy tool with no annotations, the description covers the action, the trigger conditions, every parameter, and the dry-run safety path. Missing pieces are secondary details like overwrite semantics and auth prerequisites, and the return-values block is unnecessary since an output schema 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 0%, so the description must compensate, and it documents all five parameters: repo_path, workspace_id (as a UUID), branch_or_commit (default HEAD), conflict_resolution (e.g. 'manual'), and dry_run (compute without publishing). It does not enumerate the allowed conflict_resolution values beyond 'manual', which is the only real 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?

States a specific verb and resource: deploying a local Git repo with PBIP projects into a Fabric workspace. This clearly distinguishes it from the reverse-direction sibling commit_workspace_to_git and from deploy_to_workspace. An agent can identify the operation without opening the schema.

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

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

Provides explicit 'Use this tool when the user asks to' bullets covering synchronization/publishing and updating items from version-controlled PBIP files. It gives clear positive triggers but never names alternatives (e.g. commit_workspace_to_git for the opposite direction) or states 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.