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

With no annotations, the description carries the full load and does it well: it discloses that results are a static heuristic from M text rather than proof, names the source types that never fold, and flags a surprising failure mode (row filters running locally after folding ends, meaning the source sent every row). It stops short of stating read-only/permission characteristics or cost, which is the only 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?

One dense paragraph, front-loaded with the core purpose, then findings, then caveats and alternatives. Nearly every clause carries information; it is long but not padded, though it could be broken into a purpose sentence plus a limitations sentence for scannability.

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

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

An output schema exists, so return values needn't be spelled out, and the description covers the interpretive framing an agent needs. The missing piece is parameter documentation: for a 2-param tool with zero schema coverage, the description leaves both inputs undefined, which is enough of a hole to keep this from being complete.

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

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

Schema description coverage is 0% for both parameters, and the description never mentions 'instance' or 'include_steps'. The agent must infer from 'per query' that instance identifies the query, and has no guidance at all on what include_steps toggles or when to enable it — a real gap for a tool whose output verbosity depends on that flag.

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

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

Opens with a precise verb+resource ('Static estimate of query folding per query') and then enumerates exactly which findings it produces: foldable steps, the first non-folding step, post-fold local row filters, Table.Buffer, and cross-source merges. That level of specificity distinguishes it from siblings like diagnose_power_query or find_query_diagnostics without needing their schemas.

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

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

Explicitly routes the agent elsewhere: confirm results with 'View Native Query' and use read_mashup_traces for the engine's own folding-failure reports. It also states a scope rule (SharePoint/file sources never fold), so the agent knows when this tool's output is meaningful versus when a different tool is the right call.

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: 'Get' signals a read-only operation, and it discloses a real behavioral caveat by distinguishing exact table byte totals from best-effort labeling of individual objects. It does not mention cost/latency of scanning a large model or instance targeting requirements, which are the remaining gaps for an unannotated 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 what is returned, then why it matters, in two tight sentences with no filler. Minor verbosity in the DAX Studio/Tabular Editor aside, but it earns its place by conveying provenance.

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 needn't be spelled out, and the efficiency-review framing is complete. However, for a two-parameter tool with zero schema description coverage, leaving top_n and instance entirely unexplained is a meaningful omission that could cause a wrong or defaulted 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% and the description mentions neither parameter. 'top_n' is genuinely ambiguous (top N tables? columns? storage objects?) and 'instance' is undocumented as to expected format or source. The description must compensate here and does not.

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

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

States a specific verb and resource: retrieve VertiPaq storage byte totals per table plus the largest storage objects/columns. It also anchors the concept to known tooling (DAX Studio / Tabular Editor VertiPaq Analyzer), which tells an agent exactly what class of output to expect and separates it from generic sibling tools like get_model_summary or list_tables.

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 usage context ('Use this for efficiency review') and concrete interpretations of results (unused high-cardinality column, text column to split, excess history import). It stops short of naming an alternative sibling or a when-not-to-use condition, so it is strong but not complete 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 burden: it discloses that this is a listing/analysis operation and spells out the four analytical dimensions returned, including the non-obvious isolated-tables detection. It does not state read-only nature outright (only implied by 'List') or note any cost/scope caveats, but the flag enumeration is substantive behavioral context.

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

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

Front-loaded with the action and the flag taxonomy, then immediately the differentiating routing sentence. Mild redundancy in the parenthetical 'isolated from the rest of the model', which restates 'have no relationships at all', but overall 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 values need no explanation, and the design-issue framing fully covers when to reach for it. The only real gap is the undocumented 'instance' argument, which is the one thing an agent must 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?

The single required parameter 'instance' has 0% schema description coverage, and the description says nothing about what an instance is, where it comes from, or what form it takes. With low coverage the description was expected to compensate and does not.

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

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

States a specific verb and resource ('List relationships with modeling-analysis flags attached') and enumerates exactly what the flags cover: many-to-many, bidirectional cross-filter, inactive, and isolated tables. It names the sibling it differs from (list_relationships) so an agent can route without opening 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?

Explicitly says 'Use this over list_relationships when the goal is spotting model design issues rather than just reading the raw list' — a clear when-to-use plus a named alternative and the condition that selects it. Nothing left to inference.

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

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

With no annotations at all, the description carries the full disclosure burden. It does add real behavioral insight — notably that swallowed `try ... otherwise null/false` errors let refreshes succeed with missing data, and that SharePoint.Files enumerates the whole site before filtering — but says nothing about read-only vs. mutating behavior, required access to the model/mashup, or cost of the scan.

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?

Information-dense with no filler, and the topic is front-loaded. However it is a single comma-spliced run-on list of a dozen checks, which makes it harder to scan than a short purpose sentence followed by grouped bullets.

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 needn't be explained. But for a two-parameter analysis tool with zero annotation coverage, leaving the required `instance` argument undefined and not stating whether this is a safe read-only inspection is a meaningful omission.

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% for both parameters. The description never explains the required `instance` parameter (which instance — model, workspace, site?), and `include_row_counts` is only obliquely hinted at by 'queries that never reduce columns or rows.' The most important parameter is left entirely unexplained.

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

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

The opening phrase 'SharePoint loading review' plus the enumerated anti-patterns makes it clear this is an audit of SharePoint-oriented Power Query loading patterns, distinguishing it from siblings like analyze_sql_queries or analyze_folding_risk. It never states plainly that it returns findings/report, so it reads as a topic list rather than a described action.

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

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

The SharePoint framing implies the use case (models pulling data from SharePoint lists/files), but there is no explicit when-to-use, no prerequisites, and no named alternative among the many analyze_*/diagnose_* siblings. Usage is inferable only from subject matter.

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: it does disclose the full scope of inspection and hints at output (it 'lists navigation-style SQL queries'), which is more than most. It never states that it is read-only/non-mutating, what it needs from the target model, or whether it can run against a live vs. offline file — meaningful gaps 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 with the core action, and the enumerated checks do earn their space by letting the agent judge relevance. But the second half is a breathless comma-run of a dozen items that reads as generated list-dump rather than structured prose, impairing scanability.

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

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

An output schema exists, so return shape needn't be described, and the analytical scope is well covered. The missing pieces are the sole required parameter and any statement of read-only behavior — for a diagnostic tool with no annotations, that leaves a gap an agent must resolve by trial.

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

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

There is one required parameter, 'instance', with 0% schema description coverage, and the description never mentions it — not what an instance is (Power BI Desktop? AS server? PBIX path?), not its format, not how to discover valid values. With a single undocumented param the agent is left to guess at invocation.

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 (review hand-written SQL embedded in M code, citing [Query=...] and Value.NativeQuery) and enumerates the exact anti-patterns it flags, so the agent knows precisely what class of problem it surfaces. It stops short of explicitly naming how it differs from nearby tools like find_query_diagnostics or analyze_folding_risk, though the 'can fold' note gestures at the latter.

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

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

Usage is only implied: an agent can infer 'call this when auditing native SQL in Power Query/M code,' but there is no statement of when to prefer it over analyze_folding_risk, diagnose_power_query, or find_query_diagnostics, and no prerequisites or exclusions. The check list helps the agent decide relevance but not selection.

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

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

With no annotations, the description carries the full burden and does so: one ranked list is returned, a failing check surfaces in `checks_failed` without suppressing other results, and `not_checked` discloses audit blind spots. It also states the pbix_path default, which is materially useful behavior for an agent to know.

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 entry-point directive is front-loaded, the long parenthetical of check categories is efficient enumeration rather than filler, and the trailing sentences each add a distinct behavioral fact. Slightly dense but no sentence is wasted.

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

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

An output schema exists so return values need not be explained, and the description still clarifies the important result fields (checks_failed, not_checked). For a high-complexity aggregate tool the behavior story is complete; only the undocumented parameters keep 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 coverage is 0% across 4 parameters, so the description must compensate. It explains only pbix_path (defaults to the open file's path); the required `instance` parameter is completely unexplained, and include_traces / include_data_quality get no indication of what they toggle beyond their names.

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

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

States a specific action (runs every check across the whole model) plus explicit scope by enumerating the check categories, and distinguishes itself from siblings as the aggregator whose findings are tagged with the detail tool to call. An agent can tell it apart from check_relationship_integrity or analyze_folding_risk without opening a 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?

"START HERE for a full review" gives an unambiguous entry-point rule, and the note that each finding is tagged with the tool for full detail points at the alternatives. It does not state when to skip the audit (e.g. narrow single-check queries), so it falls just short of explicit when-not guidance.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the kinds of findings returned, including which loaded tables fail if a source is unreachable and which queries are orphaned, but it does not state that the tool is read-only, whether it has side effects, or what permissions are required.

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 content is a single semicolon-separated list of output attributes rather than a front-loaded statement of purpose. It is not bloated, but the structure makes the actual action harder to extract than the feature list.

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 description does not need to enumerate return values, yet nearly all of its text is spent on output details. It leaves critical gaps around the required instance parameter, when to invoke the tool, and how it differs from sibling diagnostics tools.

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

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

The single required parameter, instance, has 0% schema description coverage, and the description never mentions it. The agent receives no explanation of what instance should contain or how it affects the analysis.

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

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

The description identifies the resource — the query dependency graph — and enumerates what it can reveal, such as chain depth and circular references. However, it opens with a noun phrase rather than a specific verb and does not distinguish this tool from sibling diagnostics tools such as find_query_diagnostics or diagnose_power_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?

It states no conditions for when to use this tool versus alternatives, no prerequisites, and no exclusions. The list of graph facts implies refresh-dependency auditing, but the agent must infer that context from the name alone.

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

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

With no annotations, the description carries full burden, and it does explain the detection logic: many-to-one flagged on one-sided misses, one-to-one/many-to-many only when unmatched on both sides. It omits whether the tool is read-only (implicit from the nature of a check), how expensive the scan is, and what happens when the relationship list exceeds the default cap of 60.

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

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

Three tight sentences, front-loaded with the core computation and followed by the failure mode it detects. Dense but every clause adds diagnostic meaning; only the parenthetical about wrong columns is slightly compressed.

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 explanation is not required. However, for a two-param tool with zero schema coverage, the description should at least note the instance scope and the relationship cap; the absence of the truncation behavior is a real gap for correct interpretation of results.

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 two parameters, and the description never mentions either one. The 'instance' parameter and especially 'max_relationships' (default 60, which silently truncates scope) are undocumented anywhere, so an agent cannot know that coverage may be incomplete.

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

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

The description names a specific operation: counting key values on each relationship side that have no match on the other, which tells an agent exactly what the tool computes. It stops short of distinguishing itself by name from the sibling analyze_relationships, leaving the agent to infer which of the two relationship tools to call.

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

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

There is no explicit guidance on when to use this instead of analyze_relationships or list_relationships, nor any stated prerequisites. The symptom-oriented framing ('totals stop matching with no error') implies a diagnostic use case, but the agent must infer the routing decision.

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 disclose meaningful behavior: it classifies source types and flags specific risks such as gateway requirements, local paths, HTTP, personal OneDrive dependence, duplicate targets, and resolved parameters. It does not state permissions or read-only behavior explicitly, but the classification purpose is clear and the output schema can carry return details.

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 and then enumerates relevant problem categories efficiently. It is dense but appropriately sized for a diagnostic classifier, though the single long sentence is somewhat run-on.

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

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

The output schema exists, so return values need not be explained, and the description sufficiently covers the kinds of problems detected. However, it does not explain the required instance input or provide explicit usage boundaries relative to the many sibling tools, leaving meaningful gaps for correct invocation.

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

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

The single required parameter, instance, has 0% schema description coverage and is never mentioned in the description. The description gives no meaning, format, or accepted values for instance, so it does not compensate for the schema gap.

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

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

The description clearly states the action and resource: classifying every data source the model reads. It also differentiates itself from simpler listing tools by emphasizing problem detection for SQL/SharePoint/OneDrive dashboards. It stops short of explicitly naming sibling alternatives such as list_data_sources or analyze_sharepoint_patterns.

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

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

Usage is implied by the dashboard-audit and connection-problem framing, but there is no explicit guidance on when to use this versus list_data_sources or other diagnostics. The agent can infer that this is for connection-risk assessment, but alternatives and exclusions are not stated.

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

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

With no annotations, the description carries the behavioral burden and does well by explaining that comparison scope depends on whether the inputs are open files or .pbix paths. It discloses the compared artifact types in each mode but does not explicitly state read-only behavior, permissions, or error handling.

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 and compact. Every sentence adds useful information: purpose, parameter forms, mode-dependent comparison scope, and use cases.

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 explained, and the description adequately covers the two input forms and what gets compared in each mode. It is slightly incomplete because it does not resolve mixed input types or specify error behavior for invalid paths or non-open files.

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 define left and right, and it does: each can be an open file name from list_open_files or a .pbix path. It leaves a minor ambiguity about whether mixing an open file and a .pbix path is allowed.

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: "Diff two dashboards." It clearly distinguishes this from sibling tools like audit_dashboard or review_file by focusing on comparison and naming the exact objects that can be diffed.

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

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

It gives clear usage context ("backup vs current, or before/after a change") and points to list_open_files for resolving open-file names. It does not explicitly state when not to use it or name an alternative comparison tool, so it falls short of a 5.

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

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

With no annotations, the description must carry the full behavioral burden. It does well on output shape (error messages, stale-refresh classification) and asserts the result is 'live, authoritative' and 'fast,' but never clarifies whether invoking it triggers an actual refresh/query execution or only inspects cached metadata — a critical side-effect question for a Power Query diagnostic.

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

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

Three tight sentences, front-loaded with the core action and output, followed by the routing advice. Every clause — error message detail, stale-refresh definition, authoritative-signal claim — adds decision-relevant 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?

An output schema exists, so return values are already covered, and the description does supply the diagnostic semantics well. However, for a single-param tool the undefined 'instance' argument and the unaddressed refresh-vs-read behavior leave real gaps an agent must guess at before invoking.

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

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

The single required parameter 'instance' has 0% schema description coverage and is never mentioned in the description. The agent gets no hint about whether it expects a PBIX path, server/workspace name, or connection identifier, so the description leaves the only input entirely undefined.

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 (health check across every table's Power Query load) and enumerates the two concrete findings it returns: tables that errored on last refresh with the actual error text, and tables whose refresh predates their last query edit. It is clearly separable from neighbors like check_relationship_integrity, find_query_diagnostics, and list_power_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?

Explicitly sequences the workflow: 'check this first' for the broken/not-broken signal, then 'use list_power_query to read the M code ... for whichever table shows a problem.' It names the alternative tool and the condition that selects it, leaving nothing to inference.

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

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

With no annotations, the description carries the burden and does so well: it discloses that Power BI Desktop isn't required, what the default scan scope is, the env-var extension path, and that `truncated=true` means results were capped. It omits things like scan cost/duration or permission-error handling, keeping it just short of a 5.

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

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

Front-loaded with the core action and the key qualifier, then defaults, then return shape. Dense and mostly waste-free, though the parenthetical return-field enumeration runs long for a tool with an output 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?

For a two-parameter discovery tool with an output schema and no destructive behavior, the description covers scope, defaults, overrides, and truncation semantics. An agent has everything needed to invoke it correctly without guessing.

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: `search_dirs` is explained as an override of the default folders and `max_results` is tied to the `truncated` flag with guidance to raise it. Some detail (e.g., whether search_dirs replaces or adds to defaults, ordering semantics of max_results) is implied rather than stated.

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 ('Scan folders recursively for .pbix / .pbit files on disk') and an important scope qualifier ('no Power BI Desktop needed'). It is clearly distinguishable from every sibling, which are model/report analysis tools rather than disk discovery.

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

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

Explains default behavior (Desktop, Documents, Downloads, OneDrive folders), how to extend it via POWERBI_MCP_SCAN_DIRS, and when to override with `search_dirs`. It doesn't name an alternative sibling to use instead, but none of the listed siblings overlap with file discovery, so context is effectively complete.

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 it does well: it explains the manual recording prerequisite, the inability to trigger diagnostics, the fallback behavior when diagnostics queries exist but were not loaded, and what kind of traced rows are returned. It stops short of covering row-limit behavior or instance-scoping details.

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 and prerequisite are front-loaded, and most sentences add useful context. The paragraph is dense and somewhat run-on, with minor redundancy, but it does not waste much space.

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

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

The description is strong on workflow, return content, and failure cases, and an output schema exists for return shape. However, for a tool with no annotations and 0% schema description coverage, the missing explanation of the required `instance` parameter and `max_rows` limit leaves a meaningful completeness gap.

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

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

Schema description coverage is 0% and the description never mentions either parameter. It does not explain what the required `instance` value should be or what `max_rows` controls, leaving both parameters undocumented.

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

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

The description states a specific verb and resource: finding and reading Power BI Desktop Query Diagnostics output. It clearly distinguishes this from sibling capabilities by contrasting the traced intermediate evaluation data with list_power_query's step breakdown.

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 prerequisite: a diagnostics session must already have been manually recorded via the Power Query Editor. It also states what the tool cannot do (start/stop diagnostics) and names an alternative sibling limitation, so the agent can choose correctly.

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 disclosure burden and does well: it warns the result is not guaranteed-safe-to-delete and enumerates the blind spots (DAX-only references, tooltips, drillthrough, Q&A) via the note field. It would be stronger if it stated read-only behavior or any performance/cost characteristics explicitly.

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 what the tool finds, then follows with prerequisite, then caveat — a sensible order with no filler. The sentence structure is somewhat dense with parentheticals, but every clause adds 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?

An output schema exists, so return values needn't be described, and the description still points at the `note` field for caveats. The main gap is the unexplained `instance` parameter for a tool requiring two inputs with zero schema documentation.

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

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

Schema description coverage is 0%, so the description must compensate. It explains where pbix_path comes from, which is genuinely useful, but the required `instance` parameter is never mentioned, leaving half the required inputs undocumented anywhere.

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

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

States a specific verb and resource with precise scope: visible columns and measures no visual on any report page uses. The parenthetical clarifies the mechanism (live model cross-referenced against offline report layout), which distinguishes it from sibling listing tools like list_columns or list_measures.

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

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

Gives concrete prerequisites by naming where to obtain pbix_path (list_open_files's file_path, or find_pbix_files). It also frames the output as a lead for model cleanup rather than an authoritative deletion list, which guides interpretation. It does not, however, contrast it against neighboring diagnostics such as analyze_model_size or check_refresh_dependencies.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=false, so the safety profile is known. The description adds genuinely useful context beyond them: a full-file backup before apply, re-verification with automatic restore of the original on failure, per-action approval codes, and the PBI_MCP_EDIT_ROOT scope restriction with the off-when-unset behavior. It omits failure-mode detail such as what a rejected or expired code returns. Because annotations already carry the destructive read/write signal, the added value is real but not maximal.

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 step label is front-loaded and each sentence carries operational weight — phase, precondition, edge case, action semantics, scope. The density makes it read as one long block rather than separated clauses, which slightly hurts scanning, but there is no filler.

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

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

For a 3-parameter destructive mutation with an output schema present, the description covers preconditions, both action modes, rollback code requirements, and the environment scope, so an agent can call it correctly. Return values are legitimately deferred to the output schema, leaving the description sufficiently complete without excess.

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 carry parameter meaning, and it largely does: it defines apply versus rollback, explains that an empty approval_code triggers a code issuance rather than an action, and ties change_id to a prior propose_change. The enum values themselves are only named in the schema, not spelled out beyond their high-level semantics.

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

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

The description opens with a precise verb-plus-resource statement — step 2 apply or undo/rollback for a change created by propose_change — and names the sibling that produces the change_id. An agent can distinguish it from propose_change and the read-only list/analyze siblings 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?

It states both the precondition (explicit user approval of THAT change plus the 6-digit console code) and the prohibition (never guess a code or infer approval), plus the edge case where an empty approval_code issues a fresh code and applies nothing. The upstream tool and the prerequisite flow are explicit, leaving nothing to inference.

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

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

No annotations are provided, so the description carries the full burden. It implies read-only via 'Get' and mentions the file must be open, but does not state that it is non-destructive, whether any permissions are needed, or how large the returned lists might be—critical behavioral context is missing.

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

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

Two sentences, front-loaded with the purpose and return contents, followed by a precise parameter note. Every sentence earns its place and there is no 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?

Given the simplicity (one parameter, read-only overview) and the presence of an output schema, the description covers what the tool does, what it returns, and how to supply the instance. The only shortfall is the absence of sibling differentiation, which is more of a usage-guideline gap.

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

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

Despite 0% schema description coverage, the description fully explains the sole parameter: 'instance' is the file's display name (or port), and it tells the agent where to get it (list_open_files). This adds complete 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 ('Get an overview') and resource ('data model'), and enumerates the exact contents returned (table/measure/relationship counts plus full lists). It does not explicitly differentiate from sibling tools like list_tables or list_measures, 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?

Implies usage as an overview and helpfully points to list_open_files for obtaining the instance, but gives no explicit guidance on when to use this tool versus the many individual list_* siblings, nor any when-not conditions.

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

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

With no annotations, the description carries the burden and usefully discloses that parsing works offline without Power BI Desktop running. It also clarifies the scope boundary (no data model), though it does not explicitly state read-only/no-modification behavior or file-access requirements.

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

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

The description is front-loaded, compact, and has no wasted sentences. The key capability, offline behavior, and scope limitation are all communicated efficiently.

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

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

The output schema exists, so return-value details do not need to be repeated. The description covers the main behavior and boundary, but with no annotations and a minimally documented parameter, a little more information about input expectations or safety would make it fully complete.

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

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

Schema description coverage is 0%, so the description should compensate for the sole parameter. It implies that pbix_path refers to a .pbix file, but it does not specify whether the path must be absolute or relative, whether the file must be closed, or any other path semantics.

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

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

The description states a specific verb and resource: parse a .pbix file's report layout. It also enumerates the returned structure (pages and per-page visuals with type, title, and fields), which clearly distinguishes it from model-querying sibling tools.

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

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

It gives a clear use case (offline report-layout extraction) and an explicit exclusion: it does not include the data model, so live-model tools should be used for tables/measures/DAX. The alternative is named as a category rather than specific sibling tools, leaving some routing inference to the agent.

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, yet it only implies that the count reflects loaded (not source) data. It says nothing about whether a live connection is required, whether the value is cached, or whether the table must exist in the current model.

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

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

One sentence, front-loaded with the verb, with no filler. It is appropriately sized for a simple read tool, though it leaves no room for the guidance that is missing elsewhere.

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, but with zero annotations and two entirely undocumented parameters, the definition leaves an agent unable to confidently supply 'instance'. The 'currently loaded' nuance needs more grounding for a Power BI/Tabular context.

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

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

Schema description coverage is 0% and neither 'instance' nor 'table' has a documented format, casing rule, or example. The description does not compensate at all — it never mentions the instance parameter, which is the more ambiguous of the two.

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 ('Get the number of rows ... in a table') with a useful scoping qualifier, 'currently loaded', which signals an in-memory model context. It does not, however, distinguish itself from nearby siblings such as profile_table or get_model_summary, which could also report row counts.

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

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

There is no guidance on when to use this instead of profile_table, list_tables, or get_model_summary, nor any stated prerequisite (e.g. model must be open/connected). The agent must infer the choice purely from the name.

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 disclosure burden. 'Get' and 'list' strongly imply a read-only enumeration and the description makes clear the output covers all three DAX object types, but it says nothing about permission requirements, cost/size of the response on large models, or whether the scan is expensive. Adequate for a simple read tool, but not rich.

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

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

Front-loaded with the core scope ('every piece of DAX in the model') followed by the enumeration and then the usage cue. Three tight sentences with minimal filler, though 'in one place' is slightly redundant with the list itself.

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 explanation is not needed, and the description covers what is included in the result set. However, it omits the only parameter ('instance') entirely and gives no signal about result volume on a large model, leaving a gap for an agent deciding how to call it.

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%: the single required parameter 'instance' has no description in the schema, and the tool description never mentions it at all. With one undocumented parameter, the description fails to compensate for the coverage gap, leaving the agent to guess what 'instance' refers 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?

States a specific verb ('Get every piece of DAX') and enumerates the exact resources returned: measures, calculated columns, and calculated tables with full expressions. It also distinguishes itself from siblings by framing the result as a consolidated view rather than 'pulling measures and columns separately', which differentiates it from list_measures and list_columns.

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

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

Gives a clear use case: 'overall DAX audit/review rather than pulling measures and columns separately', which effectively routes the agent away from the narrower sibling tools. It lacks explicit exclusions (e.g., when to prefer run_dax_query or list_measures), so it stops just short of a full when/when-not treatment.

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 implies read-only via "List" and discloses the shape of what comes back (data type, hidden flag, DAX expression for calculated columns). It says nothing about permissions, whether hidden columns are included by default, or model/instance scoping — gaps relevant 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?

Two short sentences, front-loaded with the scope decision and followed by the returned fields. Nothing is wasted and no sentence restates the name.

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 explaining return values is not required, and the description does just enough on scope. However, for a two-parameter tool whose schema documents neither parameter, leaving the required `instance` argument entirely undefined is a meaningful omission.

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

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

Schema description coverage is 0%, so the description must compensate. It explains `table` well as an optional narrowing filter, but `instance` — a required parameter — is never clarified anywhere, leaving half the parameter surface undefined.

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 and resource ("List columns") plus its scope (whole model or one table), so an agent can immediately tell it apart from list_tables or list_measures by resource. It stops short of naming any sibling or stating an explicit contrast, so it lands just below the top band.

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 two operating modes are stated clearly: omit `table` for the whole model, supply it for a single table. Beyond that there is no guidance on when to prefer this tool over list_all_dax_expressions, find_unused_fields, or profile_table, and no exclusions or prerequisites are given.

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

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

With no annotations, the description carries the burden and does well: it discloses the scanning mechanism and the return content, namely distinct connections plus which queries use them. It does not discuss permissions, performance, or connector-detection limits, but the read-only inventory nature is reasonably clear from the text.

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 action and mechanism, then follows with practical scenarios. It is longer than necessary in places, especially the example list, but no sentence is pure filler. Overall it remains readable and focused.

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

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

The tool has an output schema, so the description need not detail return values, and it already explains enough about output shape. But the required 'instance' parameter is undocumented in both schema and description, and there are no annotations to cover safety or behavior. It is adequate for purpose but incomplete for invocation.

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

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

The only parameter is required and named 'instance', but the description never explains what an instance is, what format it expects, or how to obtain it. Schema description coverage is 0%, so the description needed to compensate and does not. This is a meaningful gap for the single required input.

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

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

The description uses a specific verb and resource: inventory every data source the model connects to. It explains the mechanism, scanning table and shared query M code for connector function calls, which distinguishes it from simpler listing tools. An agent can tell what this tool does 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 concrete usage scenarios such as spotting a dev/test server in production or confirming expected data sources. However, it does not explicitly say when not to use it or name alternatives such as classify_connections or analyze_sharepoint_patterns. The context is clear but lacks exclusion 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 disclosure burden. It describes the conceptual output (hierarchies with ordered levels) but says nothing about read-only behavior, permissions, empty results, or how the required instance is resolved; with an output schema present, return-value description earns little extra credit.

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

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

Two clauses, front-loaded with the verb and resource, and the examples earn their place by clarifying what a hierarchy is. Slight verbosity from dual examples, but no wasted sentences.

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 low-complexity read-only list tool with an output schema, the description adequately covers what is returned and its scope. However, it omits the semantics of the required 'instance' parameter and gives no behavioral cues to substitute for the missing annotations, leaving clear gaps.

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

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

The single required parameter 'instance' has 0% schema description coverage and is never mentioned in the description. The description cannot compensate, leaving the agent to guess what 'instance' means (model name, connection, file path). A 2 reflects that only the broader tool context hints at its meaning.

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

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

States the specific verb 'List' and resource 'user-defined hierarchies', gives concrete examples (Year > Quarter > Month), and explicitly contrasts with 'flat tables/columns', which implies a boundary against list_tables/list_columns. It does not name a sibling tool directly, so it stops short of a 5.

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

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

The phrase 'for a complete picture of the model's structure beyond flat tables/columns' implies when to reach for this over flat-table listing, but there is no explicit when/when-not guidance and no alternative tool named. Usage must be inferred from the scope clause.

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 does disclose the return payload (DAX expression plus format string), which is genuinely useful, but says nothing about read-only semantics, permissions on `instance`, or whether large models produce an unwieldy response. An output schema exists, which lowers the bar slightly, but the operational profile is largely unstated.

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

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

Two tight sentences with no filler; the default scope is stated first and the narrowing condition follows. Every clause carries 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 return-value side is well covered, helped by an existing output schema. But the required `instance` argument is left unexplained and there is no note on response size or scoping for large models, which matters for an enumeration tool over an entire semantic model.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the optional `table` filter reasonably well, but the required `instance` parameter is never mentioned at all — the agent gets no clue that it must supply a model/instance identifier. One of two parameters is effectively undocumented in both schema and description.

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

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

States a specific verb and resource ('List DAX measures') with explicit scope: whole model by default, or one table when `table` is supplied. It also names what each result contains (DAX expression and format string). It does not distinguish itself from the similarly-purposed sibling list_all_dax_expressions, 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 description implies usage through the conditional 'or for one table if `table` is given', which tells the agent how to narrow the listing. However, it offers no guidance on when to prefer this over list_all_dax_expressions, list_columns, or list_tables, and no exclusions or prerequisites are stated.

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

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

No annotations exist, so the description carries the burden and does so well: it discloses the empty-list case when Power BI Desktop is not running, the meaning of model_loaded=false (closed, still opening, or a dialog is open), and the consequence that every model tool will fail. It never explicitly states this is a side-effect-free read, which is the one 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?

Front-loaded with the core action, then the returned handle, then the failure-mode caveat. The parenthetical 'closed, still opening, or a dialog is open' is slightly verbose but each clause disambiguates a real state an agent would otherwise misread.

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 shape need not be restated, yet the description adds the one field whose meaning is non-obvious (model_loaded) and the empty-list edge case. For a zero-parameter discovery tool, 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?

Zero parameters, so baseline 4 applies. The description instead invests in return-value semantics (the 'instance' handle, model_loaded), which is useful but belongs to output rather than input interpretation.

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 ('List every Power BI Desktop file currently open on this machine') with an explicit scope qualifier ('currently open') that separates it from the sibling find_pbix_files, which searches disk rather than live instances. The second clause names its downstream role — supplying the 'instance' identifier the other model tools need.

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?

Implied clearly as the entry point of the model-tool workflow ('the identifier to pass to the other model tools'), and it gives an actionable branch: if model_loaded is false, ask the user to open the file. It does not explicitly contrast with find_pbix_files or state prerequisites, so it falls short of full when/when-not guidance.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that the steps are a structural breakdown of M source text, not a live evaluation, and that data at each step cannot be shown. It also describes filtering behavior, default `include_steps` behavior, inclusion of refresh state and `error_message`, and the alternative diagnostics tool.

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

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

The description is front-loaded with the core purpose and is generally efficient for a complex tool. Some sentences are dense, but the detail about limitations and alternatives earns its place rather than being 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 description need not enumerate return fields, but it still explains what the returned data represents and what it cannot represent. Given the tool's complexity and lack of annotations, the description is complete enough for correct invocation and interpretation.

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 add parameter meaning. It richly explains `table` filtering and the default `include_steps` behavior, including subtle shared-query scoping, but it does not explain the required `instance` parameter at all.

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

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

The description names a specific verb and resource: get the Power Query (M) code behind the model, including loaded tables and shared queries. It clearly distinguishes this tool from a simple diagnostics tool and from the tabular model itself, so an agent can tell what it returns 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 explicitly explains when to use the `table` filter and how shared queries behave, and it names `diagnose_power_query` as the alternative for refresh state/errors without M text. The distinction between structural M-source inspection and live step evaluation is also stated, leaving little ambiguity about when this tool applies.

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 partially does: enumerating returned attributes makes clear this is a read-only metadata enumeration and tells the agent what data to expect. It says nothing about scope (single instance? all tables?), permissions, or volume, which matters for a model-wide listing.

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

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

One sentence, front-loaded with the verb and resource, followed by the field list. Every clause carries information; no filler.

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

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

An output schema exists, so needing to explain return values is reduced, and the enumeration of fields is a bonus. But with no annotations and an undocumented required parameter, the definition leaves real gaps for an agent trying to call it correctly on a specific instance.

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

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

The single required parameter 'instance' has 0% schema description coverage and the description never mentions it, so the agent must guess whether it is a server name, file path, or model identifier. This is exactly the case where the description needed to compensate for the schema and does not.

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

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

States a specific verb (List) and resource (relationships between tables), and enumerates the fields returned: from/to table and column, cardinality, active flag, cross-filter direction. That distinguishes it from siblings like analyze_relationships or check_relationship_integrity, though it never names them explicitly.

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

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

There is no guidance on when to pick this over analyze_relationships, check_relationship_integrity, or list_hierarchies — all plausible adjacent choices. The only signal is the word 'List', which implies a plain enumeration rather than analysis, and that is left to inference.

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

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

With no annotations, the description carries the burden and does disclose meaningful behavior: it returns per-table filter expressions and flags tables visible with no row filter, and it warns that RLS is not surfaced unless queried. It doesn't state permission requirements or confirm read-only semantics explicitly, but 'List' plus the described output makes the read-only profile clear enough.

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 resource and the unfiltered_tables flag are front-loaded, and the closing sentence justifies the tool's existence rather than padding. Slightly verbose in the second half but every sentence adds information an agent can act on.

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 explanation is not needed, and the description covers the salient output concept (unfiltered tables). The undocumented required 'instance' parameter leaves a real hole for an agent deciding how to invoke it, so it is only minimally complete.

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

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

The single required parameter 'instance' has 0% schema description coverage and the description says nothing about what an instance refers to, what format it takes, or which instance to pass. For a one-parameter tool this is the only real gap, but it is a complete one.

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 ('List row-level security (RLS) roles and each one's per-table filter expression') and adds a distinguishing output trait (unfiltered_tables flag). No sibling tool covers RLS, so the agent can identify it unambiguously from the name plus description.

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

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

Explicitly frames when this tool matters: 'RLS is invisible unless specifically checked, so this is exactly the kind of thing a "who can see what" or security-focused review needs.' That is a clear trigger condition. It stops short of naming an alternative or an explicit when-not-to-use case, which keeps it below 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 implies a read-only listing and hints that some tables may lack visibility/description metadata ('where available'), but says nothing about whether hidden tables are included, prerequisites on the instance, or permissions.

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

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

A single front-loaded sentence with no filler; the 'where available' hedge is meaningful, not padding. Slightly more could be said without 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?

The presence of an output schema relieves the description of explaining return values, but with no annotations and an entirely undocumented required parameter, the definition leaves key invocation details unresolved.

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?

One required parameter ('instance') has 0% schema description coverage and is never mentioned in the description. The agent cannot tell from either field whether instance means a PBIX file, a connection, or a model ID.

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 ('List every table in the data model') and adds the scope of returned metadata. It is clearly distinct from siblings like list_columns and list_measures by resource, though it never names an alternative explicitly.

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

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

There is no guidance on when to call this versus alternatives such as list_columns, get_model_summary, or analyze_model_size. The agent must infer usage purely from the resource name.

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 at all, the description carries the full burden. It does disclose useful behavior: which conditions get flagged (entirely blank, constant, text at truncation limit, placeholder dates 1900/9999) and that key_columns triggers duplicate/blank-key checks. It never says whether this reads the model or hits the underlying source, gives no cost/performance signal for a potentially expensive per-column scan, and leaves the max_columns cap (default 80) unexplained.

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

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

The core purpose is front-loaded in the first clause and the output/flag list follows compactly; the closing sentence covers the two nontrivial parameters. It reads as a single dense run-on sentence with a mid-sentence line break, but nearly every clause carries 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?

An output schema exists, so the return shape needn't be spelled out. However, for a 6-parameter profiling tool with no annotations, the definition omits whether profiling runs against the model engine or the data source, how the max_columns cap affects results, and any performance expectation — gaps that matter for correct invocation.

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

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

Schema description coverage is 0% across 6 parameters. The description does real work for two of them — it explains that key_columns checks duplicates and blank keys, and that expected_row_count is compared against the actual row count to flag a mismatch — but consumes the rest as obvious (instance, table) or silent (columns scoping, max_columns default 80). Partial compensation, not full.

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 ('Data-quality profile of one loaded table') and enumerates exactly what is computed: blanks, distinct count, min/max, longest text, plus flags for blank/constant columns, truncation-limit text and placeholder dates. This clearly differentiates it from siblings like get_table_row_count or list_columns, which only return structural information.

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

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

Usage is implied by the framing — you profile a table whose data quality you doubt — and the description hints at when to use the optional checks ('e.g. COUNT(*) you ran on the source' for expected_row_count). But there is no explicit when-to-use / when-not-use guidance relative to alternatives such as check_relationship_integrity or find_unused_fields.

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

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

The description is behaviorally rich ('Changes NOTHING: validates the result and returns a diff, the affected objects and the risk', plus the env-var sandbox rule and member usage for .pbix/.pbit). But it directly conflicts with the declared destructiveHint=true: an agent cannot tell whether this call mutates state or not, and the reconciliation (that finish_change performs the write) is left implicit.

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 step and the verb, then the no-mutation guarantee, then constraints. Six sentences is on the long side, but the approval workflow and sandbox rule are high-value and every sentence carries actionable 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?

An output schema exists, so return-value detail is not required, and the description still names what comes back (diff, affected objects, risk). The sandbox and approval rules complete the operational picture; only the mutation-vs-destructiveHint ambiguity keeps it from being fully complete.

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

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

Schema description coverage is 0% and all six parameters are bare titles, so the description must compensate; it does for the critical ones by defining exact-match semantics for old_text, the expected_count occurrence constraint, member for .pbix/.pbit, and implicitly the edit-root restriction on path. reason is never explained, which is the only meaningful 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 ('proposes replacing exact old_text with new_text in a file') and enumerates the supported file types. The 'STEP 1 of any edit' framing distinguishes it cleanly from the sibling finish_change, which is obviously the later step.

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 routing: this is the mandatory first step of any edit, the diff must be shown verbatim and explicit approval obtained before proceeding. It also states the hard precondition that editing works only on copies under the PBI_MCP_EDIT_ROOT environment variable and that originals are refused, so the agent knows when a call will fail.

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 the log location scope (all files in the window) and a meaningful limitation ('Request bodies aren't logged, so paging can't be proven'). It omits any mention of permissions or data-sensitivity implications of reading a %USERPROFILE% path, which keeps it from a 5.

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

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

Front-loaded with the core action and dense with useful detail; nearly every clause carries information. The embedded path parenthetical interrupts the opening sentence slightly but remains valuable.

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 shape needn't be described, and the read-only nature is implicit. For a 2-parameter diagnostic tool the description covers scope, contents, and limits well; the only real gap is the unexplained `since_minutes` parameter.

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

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

Schema coverage is 0%, so the description must compensate. It explains `instance` well (matching SharePoint list IDs to model queries), but `since_minutes` is never mentioned despite being the time-window control. One of two parameters is undocumented, so it lands at minimum-viable-plus.

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 ('Read') plus a precisely identified resource ('Power BI Desktop's own mashup-engine trace logs' at a concrete path), and it enumerates what the logs contain (request counts, HTTP failures, durations, folding-failure reports, crashes). The claim that it is 'the ONLY source of connector-level runtime evidence' clearly separates it from sibling analysis tools like analyze_sql_queries and diagnose_power_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?

It gives explicit usage context: pass `instance` to tie SharePoint list IDs to this model's queries, and it warns that the logs cover every file opened in the window (so results may include other files). It does not name a sibling alternative or state a when-not-to-use condition, keeping it below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description still adds real value by disclosing that the compressed model and Power Query container are never read and that passwords/tokens are returned as [REDACTED]. It does not discuss output size, truncation behavior, or what a listed-parts response looks like, leaving a few behavioral gaps.

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

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

The core action, the allowed file types, and the critical two-step .pbix/.pbit procedure are all front-loaded, and every sentence adds information. The second sentence is dense and chains several clauses, but nothing is redundant.

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

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

An output schema exists, so return-value shape need not be explained, and the file-type, member-listing, exclusion and redaction details cover most of what an agent needs before calling. The remaining gap is the pagination/truncation semantics of offset and max_chars, which an agent must infer when reading large files.

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

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

Schema description coverage is 0%, so the description carries the full burden: it explains `member` well with a concrete example (Report/Layout) and the two-step listing pattern, and file extensions imply `path` format. However, `offset` and `max_chars` (the truncation window, presumably) are never mentioned, so half the parameters remain undefined for the agent.

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

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

States a concrete verb and resource ('Read one Power BI file's TEXT without changing anything') and enumerates exactly which file types qualify (.pbip/.pbir/.pbids/.rdl/.tmdl, PBIR .json in a *.Report folder, a part of .pbix/.pbit). That makes it distinguishable as a raw-text reader from the structured-analysis siblings, though it never explicitly contrasts itself with closer siblings such as get_report_layout or read_mashup_traces.

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 procedural guidance for the tricky case: for .pbix/.pbit call first WITHOUT `member` to list parts, then WITH `member` (e.g. Report/Layout) to read one. It also states exclusions (DataModel and DataMashup are never read), which steers the agent away from fruitless calls. It stops short of naming an alternative sibling for cases this tool cannot serve.

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 behavioral burden and does well: it specifies the return shape, row cap behavior, and the truncation warning. It does not explicitly state whether the query is read-only or what permissions are required, which is a minor remaining gap for an arbitrary query 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-loads the core purpose and usage, then adds return shape and truncation warning without filler. Every sentence contributes operational guidance.

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

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

Given the simple three-parameter schema and available output schema, the description is complete enough: it explains the query format, row limit behavior, and result shape. The only minor omission is explicit instance identifier semantics, which is not enough to reduce the score.

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

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

Schema description coverage is 0%, so the description must compensate. It adds useful meaning for dax_query by specifying EVALUATE and optional DEFINE MEASURE/VAR blocks, and for max_rows by explaining truncation behavior, though instance semantics remain largely implied by 'open Power BI file.'

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: run an arbitrary DAX query against an open Power BI file. It also distinguishes itself from higher-level sibling tools like list_tables and list_measures by positioning itself as the fallback for ad hoc queries.

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

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

Explicitly says to use this for anything the higher-level tools do not cover and gives concrete examples such as ad hoc aggregations, filtering, top-N, DISTINCT lists, and testing candidate measure definitions. The when-to-use guidance 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.