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

With no annotations, the description carries the full behavioral burden. It does disclose the upsert nature ('create or update') and that it writes directly via TOM, which is meaningful, but it omits permissions, failure behavior, and what happens to a pre-existing measure of the same name.

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

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

Purpose is front-loaded, followed by the alternative-tool caveat and then a tight per-parameter list. No filler sentences, and each line earns its place.

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

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

An output schema exists so return values need not be explained, and the description covers the parameters and the key alternative. The remaining gap is behavioral detail (auth, overwrite-on-existing, bulk limits) for an unannotated mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate and largely does: it annotates port/model_id (source: list_local_reports), table_name, measure_name, expression, format_string and description with examples. Examples add real value beyond the bare schema property names.

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

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

The description states a specific verb pair plus resource: create or update a DAX Measure in the currently open Power BI Desktop model via TOM. That is unmistakably different from execution-oriented siblings like execute_dax_local. It is clear, though it does not explicitly name the sibling it complements.

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 when-not and alternative: for bulk/complex modeling operations prefer the Microsoft powerbi-modeling MCP if available. This routes the agent usefully, though it gives no guidance on local vs service model targets or on the create-vs-update 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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses mutation context (TOM/open model), cardinality direction, and the active default, but omits error/duplicate handling, permissions, and side effects of adding a relationship.

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

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

The description is compact and front-loaded, with the core action first and parameter semantics in scannable bullets. Every line contributes; 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 mutation tool with no annotations and 0% schema coverage, the definition provides the essential relationship semantics and an alternative for bulk operations. Still, required environment parameters (port, model_id) and error/precondition behavior are missing, so an agent lacks some invocation details; output schema covers return values.

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

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

With 0% schema description coverage, the description must define all parameters, but it only explains from_table/from_column, to_table/to_column, and is_active; required port and model_id are left undocumented. It adds useful cardinality semantics for the core relationship fields but does not fully 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 states a specific action (create a Many-to-One relationship) and resource (two tables in the open Power BI Desktop TOM model). It also scopes locality via 'local' and TOM, making it distinguishable from service/other modeling tools in the sibling list.

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 routes bulk/complex modeling to the Microsoft powerbi-modeling MCP if available, implying this tool is for simpler local relationship creation. However, it does not spell out when this is preferred over other local siblings or any prerequisites beyond an open model.

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 flags a mutation ('SẼ GHI vào đây'), a concurrency constraint that data will be overwritten if the file is open, and the return payload (new page path + manual verification steps). It omits auth/permission requirements, keeping 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-loads the action, then the critical warning, then per-parameter semantics, then return value. Dense but every block earns its place; minor verbosity in the embedded JSON example is justified by the 0% schema coverage.

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

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

For a complex mutation tool with no annotations and 0% schema coverage, the description covers the write target, the required environmental precondition, all three parameters, and the return contract. Complete enough to invoke correctly, though permission/error behavior is unaddressed.

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 does: it defines the three accepted forms of report_path, the origin of kit_dir, and a full JSON shape for page_spec including role mappings per visual type and field types (Measure | Column). This adds substantial meaning the schema lacks.

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

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

States a specific verb and resource ('Dựng TRANG MỚI vào báo cáo PBIR từ template kit') and immediately scopes the mechanism ('clone-and-rebind — không dựng layout từ đầu'). This clearly separates it from siblings like distill_template (builds the kit) and list_templates (lists kits).

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 concrete prerequisite ('File .pbip phải ĐANG ĐÓNG trong Power BI Desktop') and routes the agent to relevant siblings ('tạo bởi distill_template', 'xem list_templates'). It stops short of an explicit when-not/exclusion statement, but the workflow context is strong.

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

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

No annotations are provided, so the description carries the burden. 'Mô tả' (describe) implies a read-only operation and the description usefully discloses what is returned (columns and measures), but it does not affirm non-mutation, permissions, or error behavior. Output schema exists, so return-format details are reasonably omitted.

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

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

Three short front-loaded lines with zero waste: purpose first, then per-parameter sourcing. Every sentence earns its place.

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

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

For a read-only describe tool with an output schema present, the definition covers purpose, return contents, and all three parameter sources. Nothing critical is missing, though a note on whether measures are included conditionally or scope limits would round it out.

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

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

Schema description coverage is 0%, so the description must compensate — and it does, explaining the meaning and provenance of all three required parameters (port/model_id from list_local_reports, table_name from list_tables). This is meaningful added value over bare string titles in the schema.

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

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

States a specific verb (describe) and resource (table), and names the exact return content: column names + data types plus measures defined on the table. This distinguishes it from list_tables (enumerate) and list_local_reports, though it doesn't explicitly contrast itself with them.

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

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

Gives clear prerequisite chaining by stating port/model_id come from list_local_reports and table_name from list_tables, which implicitly defines the workflow ordering. It does not explicitly state when NOT to use it, but the context is well-defined.

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

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

With no annotations provided, the description carries the full burden and discloses important behavior: auto-detection of an open report when port/model_id are blank, default output filename and directory, environment variable fallback, and a sensitivity warning about not writing to public repos. It still lacks failure-mode details, such as what happens if multiple reports are open.

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

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

The description is front-loaded with the core purpose, then uses a compact bullet list for parameter behavior and a final warning. Every sentence adds useful information, with no filler or repetition.

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

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

Given an output schema exists, the description does not need to explain return values, and it focuses on invocation behavior, defaults, and a security note. It is largely complete for a four-parameter extraction tool, though it could mention prerequisites like Power BI Desktop being open or the failure case when multiple reports are open.

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

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

Schema description coverage is 0%, so the description must compensate and it does: it explains that port/model_id are auto-detected if blank when only one report is open, and it gives defaults for output_filename and output_dir. It does not distinguish port from model_id individually, but covers all four parameters at a practical level.

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

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

States a specific verb and resource: extracting the data model structure (tables, columns, relationships, measures) of an open Power BI Desktop report into a Markdown blueprint with Mermaid ERD. This is clear enough to distinguish it from report-design or template tools, though it does not explicitly name sibling alternatives.

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

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

Provides clear context: use the output as a reference when writing DAX or designing reports. It does not explicitly state when not to use it or name alternative sibling tools, but the intended use case is unambiguous.

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

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

With no annotations, the description carries the burden and does well: it declares CHỈ ĐỌC (read-only) on the source, describes what gets written and where, and warns that output contains real business bindings that should stay in a private Knowledge Dir and not be committed. It omits auth/rate-limit context, but covers the operationally important traits.

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 action and output set, then uses a compact per-parameter list and a closing note. Every line is useful; minor verbosity in the artifact enumeration keeps it just short of maximally 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; the description instead covers inputs, destinations, workflow pairing, and the privacy caveat. For a read-only, 3-param, schema-rich tool this is complete enough to invoke correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: report_path is explained as accepting .pbip, *.Report, or definition folders; project is defined as the Knowledge Dir target with default path; out_dir is described as an override that bypasses the Knowledge Dir. This meaningfully exceeds 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 (scan/distill) and resource (entire PBIR report: pages, theme, settings), and enumerates the concrete artifacts produced (REPORT_CATALOG.md, DESIGN.md, theme/*.json). It also names the complementary sibling (distill_model_schema), so an agent can distinguish it from the model-side extractor.

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?

Clearly frames the tool as the report/design half of a two-part workflow and tells the agent to pair it with distill_model_schema for a full project profile. It adds a do-not-commit constraint, but gives no explicit when-not / alternative routing (e.g. distill_template).

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: 'CHỈ ĐỌC — không sửa báo cáo nguồn' declares the tool does not mutate the source report, and it discloses the safety-critical default (sanitize=True) with the reasoning behind it. It stops short of covering failure modes or what happens to unlisted behavior.

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

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

Front-loads the purpose sentence before per-parameter bullets, and every bullet carries real information. The heavy emphasis markers and the length of the sanitize rationale make it slightly denser than necessary, but nothing is 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 return values need no explanation, and the description covers the mutation-risk and parameter semantics an agent needs. The only gap is the undocumented kit_name parameter, which is minor for a 5-param tool.

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

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

Schema description coverage is 0%, so the description must compensate, and it documents 4 of 5 parameters in meaningful detail (report_path accepted forms, page GUID vs displayName, out_dir default location, sanitize semantics). Only kit_name is left 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?

States a specific verb ('Chưng cất' / distill) on a specific resource (one PBIR report page) and enumerates the exact artifacts produced (blueprint.md, blocks/*.json, _page.json, kit.json). This clearly separates it from siblings like distill_model_schema, distill_report_design, and apply_template.

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 sanitize bullet gives conditional guidance (set False only if the user explicitly says the kit is internal), which is genuinely useful. However, it never states when to reach for distill_template instead of apply_template or distill_report_design, so the alternative-selection guidance remains implicit.

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful policy behavior: default blocking of raw table dumps (EVALUATE 'Table' / ALL()) and PII-blocklisted columns, plus an aggregate-only policy that caps rows at 200. It stops short of stating read-only nature, permissions, or failure behavior, but the policy disclosure is substantive.

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

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

The purpose sentence is front-loaded and the parameter bullets are terse and scannable. Each line earns its place, with only mild verbosity in the max_rows policy caveat.

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 description covers the policy constraints and parameter sourcing. Remaining gaps are secondary details like pagination or error semantics for a query tool.

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

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

Schema coverage is 0%, so the description must compensate, and it documents all four parameters with concrete examples and semantics: port example ('51234'), dax_query form ('EVALUATE SUMMARIZECOLUMNS(...)'), and max_rows default/interaction with policy and the meaning of 0. Only model_id is described by reference rather than format.

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 ('execute') and resource ('a DAX query') scoped to 'the open Power BI Desktop report'. The word 'local'/Desktop implicitly separates it from the sibling execute_dax_service, but it never names that alternative explicitly, so the differentiation is left to inference.

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

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

It provides useful context, notably that model_id must be obtained from list_local_reports, which chains this tool correctly. However, it gives no explicit guidance on when to choose this over execute_dax_service or what conditions would make the sibling preferred.

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

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

No annotations are provided, so the description must carry behavioral disclosure. It states the read-only query nature, documents max_rows default 1000 with a conditional tightening to 200 for dimension columns, and cross-references execute_dax_local for policy, but it omits authentication, permissions, rate limits, and error behavior for a REST API call.

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 structured as a short intro plus three bullet points for parameters, with no wasted sentences. The policy note is brief and clearly separated.

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

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

With an output schema present, return values do not need explanation, and all parameters are described. However, for a cloud REST API tool with no annotations, the description should ideally cover authentication or permission requirements, and its policy section relies entirely on a cross-reference to execute_dax_local rather than being self-contained.

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 is the only source of parameter meaning. It documents all three parameters: dataset_id as a GUID, dax_query with a DAX example, and max_rows including its default and conditional limit, fully compensating for the schema's missing descriptions.

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

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

States a specific verb ('Truy vấn dữ liệu'), resource ('Dataset đã xuất bản trên Cloud Power BI Service'), and channel ('thông qua REST API'). It also differentiates from the sibling execute_dax_local by specifying the cloud service context and referencing that tool's policy.

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

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

The description implies usage for published cloud datasets queried via REST API, but it does not explicitly state when to choose this over execute_dax_local or any other alternative. The policy note 'như execute_dax_local' hints at shared behavior but provides no independent usage guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses the folder structure created, that INDEX and TIMELINE are registered, that all agent-created project files default to this location, and that a path is returned. It does not cover permissions, overwrite behavior for existing projects, or failure modes, keeping 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?

The description is three tightly written sentences with zero filler. The primary action (creating the project folder) is front-loaded, followed by side effects and the return value, making it easy to scan.

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

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

An output schema exists, so return values need not be explained in detail. The description covers creation, registration, default file storage, and next-step path usage, but the meaning of the required `name` parameter is left largely implicit. For a simple one-parameter tool, this is almost complete but has a notable 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 sole parameter `name` has no schema description. The description shows `projects/<slug>/`, which implies the required name is turned into a slug, but it never explicitly states what the parameter represents, its format, or constraints. This partial compensation supports a 3.

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

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

The description states a specific verb (create) and resource (new project folder `projects/<slug>/` in Knowledge Dir with artifacts/ and design/) plus secondary actions (register INDEX + TIMELINE). It is clearly distinct from siblings like setup_knowledge or log_timeline, but it never explicitly differentiates itself from those tools, so a 4 rather than 5.

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

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

It establishes clear usage context: every file the agent creates in the project defaults to this folder, and the returned path should be used for later steps. This tells the agent when to call it (before creating project files), but there are no explicit when-not conditions or named alternatives, 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?

No annotations are supplied, so the description carries the full behavioral burden. It implies a read-only status inspection but never explicitly states that it has no side effects, requires no auth, or is safe to call repeatedly. Return values are covered by the output schema, which lifts this slightly above the floor.

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 compact lines, front-loaded with what the tool does and then the critical call-order directive. The only minor waste is the '+' conjunction and duplicated bilingual phrasing, but nothing is padded.

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

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

For a zero-param tool with an output schema, the description is nearly sufficient: purpose and call ordering are clear. The gap is the failure path — it never says what to do (e.g., call setup_knowledge) when the Knowledge Dir is not yet configured, which is the most likely follow-up an agent needs.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema is effectively complete. Baseline 4 applies for a no-argument tool.

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 action: check whether the Knowledge Dir (workspace basic or remote station) is configured, plus summarize its current state. That is a concrete verb+resource pair, not a restatement of the name. Sibling differentiation is only implicit (setup_knowledge is the write counterpart), 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?

It gives an explicit ordering rule — call this FIRST before every knowledge workflow — and enumerates the affected commands (/pbi-new, /pbi-scan, /pbi-done, /pbi-pack, /pbi-recall). It does not, however, name the alternative to invoke when the check fails (setup_knowledge) or state any when-not condition.

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 discloses that the result includes connection port information (useful for wiring into a local DAX session), but says nothing about prerequisites such as Power BI Desktop needing to be running, or what happens when no reports are open.

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 sentence that front-loads the verb and resource and appends the returned port detail without any padding. Every clause earns its place.

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

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

An output schema exists, so return values need not be described, and there are no parameters to cover. The only gap is usage routing versus sibling list tools, which keeps it short of full marks.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The schema title confirms an empty arguments object.

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

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

States a specific verb (list) and resource (Power BI Desktop reports currently open on the local machine), plus the extra payload (connection port info). It implicitly distinguishes itself from list_tables and the service-side siblings, but 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?

Usage is only implied by the word 'local' and 'currently open'; there is no explicit statement of when to reach for this tool versus list_tables or the service DAX tools. An agent can infer the local-discovery intent, but nothing is spelled out.

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 does disclose one real behavioral trait — that system tables are silently filtered from the result — which the agent could not infer from the schema. It says nothing about connection/auth requirements, result ordering, or failure behavior when no model is open.

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 lines, front-loaded with the action and scope, followed by the parameter prerequisite. No filler; only slightly thin rather than padded.

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

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

An output schema exists, so return values need not be explained. For a simple two-parameter list tool the description covers scope, filtering behavior, and parameter provenance — enough to invoke it correctly, though the absence of annotations leaves the operational profile unstated.

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% (both port and model_id are bare strings), so the description must compensate. It does the most valuable thing by naming list_local_reports as the source of both values, but adds no format hints (e.g., what port looks like, whether model_id is numeric or a GUID).

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: listing tables in the currently open model, and adds a scoping detail (system tables LocalDateTable/DateTableTemplate are filtered out) that distinguishes it from a raw enumeration. Sibling describe_table is not named, so differentiation from it is only implied.

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 note that port/model_id come from list_local_reports establishes a prerequisite workflow (list reports → pick one → list its tables), which is genuine usage guidance. However there is no explicit when-not, and no routing away from describe_table or distill_model_schema for the same modeling data.

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

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

No annotations are supplied, so the description carries the disclosure burden. It usefully enumerates what a returned kit contains (blocks with verbatim visual.json by type, blueprint, page settings, design tokens), but it never states that this is a read-only operation, whether it needs authentication, or any result-size/caching behavior. The content enumeration is genuine added value; the safety profile 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, no filler. The listing action and its data sources are front-loaded, and the second sentence compactly enumerates the payload of a kit.

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 no-argument listing tool with an output schema present, the description goes beyond the minimum by sketching the shape of a returned kit, which is what an agent needs to decide whether listing is worth it. The only real gap is the lack of positioning against distill_template/apply_template.

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

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

There are zero input parameters and schema coverage is 100%, so per the rubric the baseline is 4. The description correctly does not invent parameters, and the detail about what a kit contains is really return-value context rather than parameter guidance.

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

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

States a concrete verb ('Liệt kê') and resource ('template kit báo cáo'), and even names where the items come from (repo report-templates/ and the POWERBI_TEMPLATES_DIR env var). What it does not do is distinguish itself from the template-related siblings distill_template and apply_template, so an agent must infer the relationship.

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 would reasonably read this as the discovery step before distill_template or apply_template, but the description never says when to call it, when not to, or which sibling to use for the adjacent jobs. No prerequisites or exclusion conditions 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. It usefully discloses the append-only, additive nature of the write, which tells the agent it won't overwrite history. It does not mention permissions, whether the file is created if absent, or failure behavior.

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

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

Two tight lines: the action and its append-only constraint come first, then the usage triggers. No filler, nothing redundant with structured fields.

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 append-only semantics plus triggers cover the essentials for a simple logging tool. Minor gap: where TIMELINE.md lives and whether a missing file is created.

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 enumerates all four parameters (project, event, lesson/product, link), matching the schema one-to-one, but adds no format, length, or required-vs-optional guidance beyond the 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 verb (write/ghi), a precise resource (TIMELINE.md) and scope (append-only), plus the payload fields. An agent immediately knows it appends a log line. No explicit sibling differentiation, but the resource is unlike any sibling here.

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?

"Dùng khi" enumerates four concrete trigger situations: closing a project, generating a new kit, capturing a lesson, hitting a milestone. This is clear context for when to call it, though it names no alternatives or exclusions.

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

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

With no annotations, the description carries the full burden, and it does disclose real behavior: it writes a POWERBI_PROJECT_DIR line into station/config.env, performs a backup, builds a skeleton, and is idempotent. That is substantive side-effect disclosure; only error/permission behavior is left 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?

Front-loads the primary action and location, then side effects, then the skeleton contents in a compact, scannable list. Dense telegraphic phrasing costs a little clarity 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?

An output schema exists, so return values need not be explained. The description covers location, side effects, idempotency, and generated artifacts; the main gap is the missing distinction from the sibling init_project.

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

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

Schema coverage is 0% for the single 'path' parameter, so the description must compensate. It does: it names the default (workspace/ in the checkout) and the rule that an alternate path must be outside the repo source area, adding meaning the bare string schema lacks.

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

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

States a specific verb+resource ('Thiết lập thư mục dự án' = set up project directory) and enumerates the concrete artifacts created (projects/, knowledge/ 4 axes, templates/, INDEX.md, TIMELINE.md). It does not differentiate itself from the confusingly-similar sibling 'init_project', which an agent could easily mistake for this one.

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 placement constraint (a custom path must lie outside the repo source area) but never states when this tool should be chosen over alternatives such as init_project or knowledge_status. No when-to-use or when-not-to-use guidance is present.

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