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

Annotations already declare readOnlyHint=true, so the read-only safety profile is covered; the description adds value by revealing the underlying data source and output grouping. It does not disclose behavior when the SARIF file is absent, how the limit parameter applies, or any error conditions. This is solid but not rich behavioral disclosure.

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 sentence with little filler, and every clause carries information. However, the missing verb in the opening phrase is a structural flaw that forces the reader to reconstruct the meaning, and the useful level-filter hint is placed at the end rather than up front.

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

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

For a 4-parameter read tool with no output schema and zero schema coverage, the description compensates for the missing output schema by describing result grouping but fails on inputs. The required `source` parameter is undefined and limit semantics are unmentioned, so the description is not sufficient for confident invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It documents the level filter values (Critical/High/Medium/Low), but the required `source` parameter is left entirely opaque and `app`/`limit` are not meaningfully explained. An agent cannot reliably determine what value to pass for `source`.

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 resource (AppCheckerResult.sarif saved inside the app) and the result structure (counts by level, issues grouped by rule with screen.control.property locations). This is enough to distinguish it from siblings like solution_check, which runs a check rather than reading a saved artifact. The opening phrase is grammatically malformed — a verb like 'reads' or 'returns' is missing — but the intent is inferable.

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

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

No guidance on when to use this tool vs alternatives. The description never mentions conditions, exclusions, or sibling tools, even though solution_check could plausibly be confused with reading checker results. The agent is left to infer usage context entirely.

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 goes well beyond the readOnlyHint annotation by explaining that it flags unreferenced data sources, checks meta.xml DatabaseReferences for solution sources, and reports missing columns. It also gives concrete consequences such as silent drops on save/publish and broken writes after import.

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 dense yet compact, front-loading the main purpose and then adding high-value behavioral details. Every sentence contributes useful information without repetition or 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?

The description is rich in behavioral detail and covers important failure modes, but it leaves parameter meanings unexplained and does not describe the output format. With no output schema and 0% schema coverage, this creates a meaningful gap for an agent trying to invoke the tool correctly.

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

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

The schema has 0% description coverage for its two parameters, and the description does not clearly define what 'app' or 'source' should contain. The phrase 'On a solution source' hints at the source parameter, but this is insufficient for an agent to confidently construct inputs.

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

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

The description clearly defines the tool as reporting an app's data sources with referencing formulas, plus specific analysis flags. It distinguishes itself from sibling tools like list_tables or search_formulas by focusing on data-source usage and reference integrity.

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

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

The description implies when to use it: when inspecting canvas app data sources and their formula references, or when validating a solution source. It does not explicitly name alternatives or state when not to use this tool versus related siblings.

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

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

Annotations already mark the tool as read-only, and the description is consistent with that. It adds useful behavioral context about source resolution, including multiple supported formats and the app-name fallback for multi-app solution zips. It doesn't disclose output shape or error cases, but the readOnlyHint covers the main safety concern.

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 dense but compact, with the tool's purpose front-loaded before the source-format details. The second sentence is a long clause packing several alternatives, but every part earns its place and 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 read-only overview tool with two parameters and no output schema, the description covers what the tool returns, what inputs it accepts, and when the app parameter matters. The lack of a return-structure definition is mitigated by the enumerated summary content. An agent has enough information to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry the parameter semantics, and it largely does. It defines source by its accepted formats and defines app as the logical/display name required when a solution contains several apps. This is enough for an agent to populate both parameters, though a structured parameter-by-parameter breakdown would be even clearer.

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

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

The description clearly identifies the tool as producing a summary of a canvas app's source and enumerates the included information: screens, control counts, components, control types, data sources, and app checker counts. It also specifies accepted source formats, which helps distinguish it from siblings like list_controls or canvas_data_sources. However, it does not explicitly name or contrast sibling tools, so it stops short of a 5.

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

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

The description gives concrete guidance on valid source inputs (.msapp, SourceCode folder, solution zip/unpacked folder) and explains when the app parameter is needed (when a solution zip holds several apps). This provides clear usage context, though it never explicitly states when to prefer this tool over alternatives like app_checker_results or canvas_data_sources.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds useful behavior beyond annotations: system columns are hidden by default unless include_system_columns=true, and full=true adds extra detail. It also discloses source flexibility for solution files vs. canvas app cached schemas.

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?

Dense but efficient: the primary output fields are front-loaded, optional toggles are explained, and source variants are noted. It is close to a 5, but the packed phrasing around source/app/table may require careful parsing.

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 no output schema, the description compensates well by listing what the tool returns, including columns, types, requiredness, etc. It covers most invocation concerns, but the app parameter and the exact acceptable values for source remain slightly ambiguous.

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 parameter burden. It meaningfully explains table as logical/display/entity-set name, describes source inputs, and clarifies full and include_system_columns. However, the app parameter is not explicitly described, so one of five params remains under-specified.

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

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

States a specific object of interest ('columns of one table') and enumerates the exact kinds of metadata returned. This clearly distinguishes it from sibling tools like list_tables or list_relationships, even without naming 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?

Describes when the tool is relevant: a single table's schema from a solution or canvas app, with optional modes for system columns and full metadata. It does not explicitly name alternatives or state when not to use it, but the 'one table' scope makes the context clear.

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

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

Annotations already mark the operation as readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context: it accepts zips or unpacked folders, treats formula changes as 'small diffs', and falls back to reporting changed files for anything not explicitly modeled. No contradiction with annotations exists.

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

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

The description is a single dense sentence with a clear front-loaded purpose, followed by a structured enumeration of comparison categories. It is efficient and free of filler, though the long comma-separated list could benefit from light formatting for readability.

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

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

The description covers a broad and complex comparison surface, but significant gaps remain: parameter semantics are undocumented, and with no output schema the agent is not told anything about the shape or nature of the returned diff. For a tool this complex, that leaves the definition only partially 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 must compensate for the three parameters. It only indirectly references the two solution versions and formula changes, but never names old, new, or max_formula_changes, and gives no guidance on how paths are provided or what the max_formula_changes limit controls.

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 ('What changed between two versions of a solution') and enumerates the concrete dimensions covered: tables, columns, relationships, canvas apps, flows, env vars, and changed files. This clearly differentiates diff_solutions from siblings like export_solution 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?

The description implies the tool is used to compare two solution versions, giving examples like two export_solution outputs. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or prerequisites beyond the basic input format.

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

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

Annotations indicate readOnlyHint=false (it does change the environment read-side but the description clarifies no read-side changes), openWorldHint=true, and destructiveHint=false. The description adds important context: it exports to a new timestamped folder, defaults to unpacking, takes ~1 minute, and returns zip and folder paths. It correctly clarifies that nothing changes in the environment (read-side), which is useful behavioral information beyond the annotations.

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

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

The description is concise (about 100 words) and front-loads the core action and side effect. Every sentence adds value: the default unpack behavior, the managed condition, and the expected duration are all useful and non-redundant. 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?

For a tool with 4 params and no output schema, the description covers the main steps, key condition for managed, and expected duration. It doesn't explain what the return paths are for or how to use them, but given the simplicity and the openWorldHint, this is adequate complete enough for most agents.

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

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

Schema description coverage is 0%, but the description provides meaning for key parameters: managed=true exports the managed package, unpack default is true and it unpacks. It also mentions the solution parameter implicitly, but the environment parameter is not elaborated beyond the schema. The description partially compensates for the schema's lack of descriptions, giving enough context for the main parameters.

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

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

The description clearly specifies the action ('Export a solution'), the resource ('from an allowlisted environment'), and the main side effect (creates a timestamped folder and optionally unpacks it). It also mentions the purpose ('so its tables, relationships and canvas apps can be read offline'), which helps distinguish it from sibling tools like import_solution or pack_solution.

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

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

The description explains when to use it (to read solution components offline) and gives a key condition for managed=true (only possible from the environment where the solution is unmanaged). However, it does not explicitly mention when NOT to use it or alternatives, though siblings like unpack_solution and pack_solution are implied. The guidance is clear for most use cases.

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

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

Even though readOnlyHint already marks it as read-only, the description adds substantial behavioral detail: pac ignores top/count/page, rows are capped, <order> is ignored, results are client-side sorted, and values are formatted strings. These are non-obvious execution details an agent needs before calling the 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 dense but every sentence adds a distinct, useful fact: purpose, output shape, row cap behavior, ordering behavior, formatting, and query best practice. The core purpose is front-loaded, and no filler is present.

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

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

Given the lack of an output schema, the description covers return shape and key execution limits reasonably well. It omits minor details such as how to specify the environment or exact error behavior, but these are not critical for a read-only query tool whose annotations already signal safety.

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 compensate for undeclared parameter meanings. It clarifies max_rows defaults and ceiling, explains that pac pages through all records, and advises FetchXML authoring with filters and explicit attributes. The environment parameter gets only generic 'allowlisted' context, leaving some 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 names a specific action—running a read-only FetchXML query against an allowlisted environment—and states the output format as rows of dicts. It clearly distinguishes this tool from sibling metadata/management tools like list_tables, describe_table, and export_solution.

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 read-only nature and 'FetchXML cannot modify data' statement imply this is for safe data retrieval, but the description does not explicitly compare it to alternatives or state when to avoid it. Usage guidance is present mostly for query authoring, not for tool selection against siblings.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral detail by explaining that the properties parameter limits the output to named properties. This goes beyond the schema, though it does not disclose error handling or other constraints. Given the annotations cover safety, a 3 is appropriate.

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

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

Two sentences, no wasted words. The purpose is front-loaded, and the parameter clarification follows immediately. Efficient and easy to scan.

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

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

With no schema descriptions and no output schema, the description should explain all parameters and return behavior. It describes the return structure but omits essential context for the required parameters 'source' and 'control', making it incomplete for an agent to call correctly.

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

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

Schema coverage is 0%, so the description must compensate. It explains the 'properties' parameter but leaves the required 'source' and 'control' parameters unexplained, and 'app' is not clarified either. Only one of four parameters receives meaningful description.

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

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

The description clearly states the tool retrieves a single control (or screen/App) and enumerates the specific attributes returned (type, variant, parent, children, property formulas). It distinguishes itself from siblings like list_controls by emphasizing 'One control' versus a collection.

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

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

No guidance is provided on when to use this tool vs. alternatives like list_controls or search_formulas. There is no mention of context, prerequisites, or exclusions, leaving the agent to infer use cases.

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 goes well beyond the annotations (destructiveHint=true) by explaining that 'upgrade' deletes components missing from the zip, that execution first exports a backup, and that an undo recipe is returned. It also discloses the ALLOWLISTED environment prerequisite and warnings/blockers, providing rich behavioral context that annotations alone do not convey.

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

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

The description is a single, information-dense paragraph with the primary action front-loaded. Each sentence adds value, but the enumeration of modes and behaviors could be better structured (e.g., bullet points) for scannability. It is still appropriately concise for the tool's complexity.

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

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

For a complex, destructive tool with no output schema, the description covers the critical context: dry-run behavior, mode semantics, destructive consequences, backup/undo, and the allowlist prerequisite. However, it omits semantics for three parameters and leaves 'holding' mode unexplained, so it is not fully complete. The provided context is sufficient for basic safe use.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clearly explains dry_run and mode (including the meanings of 'update', 'upgrade', and 'holding'), and relates environment to the target org. However, settings_file, force_overwrite, and publish_changes are not described, leaving a significant portion of the API 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 opens with a specific verb-resource pairing ('Import a solution zip') and immediately distinguishes the tool from siblings like export_solution or pack_solution by specifying the action and target ('into an ALLOWLISTED environment'). It also conveys the tool's core value proposition (dry-run planning vs execution).

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

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

The description provides clear context on when to use dry_run vs execution, and explains mode semantics ('update' vs 'upgrade' vs 'holding'), including a destructive caveat. However, it does not explicitly name alternatives or state when not to use this tool versus sibling tools, so it stops short of full 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?

Annotations already establish readOnlyHint=true and openWorldHint=true. The description adds useful behavioral detail beyond that: it explains that results vary by source, listing the fields returned in each mode (name, created by, modified on vs. logical name, display name, AppVersion stamp). It does not contradict the annotations.

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

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

The description is a single compact sentence that front-loads the resource and packs relevant details into parentheses. It is efficient and avoids filler, though the parenthetical structure makes it slightly dense.

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

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

Given no output schema and two undocumented parameters, the description provides a reasonable overview but omits important details: accepted values for 'source' and 'environment', how to specify an offline folder, and how this tool relates to siblings like canvas_overview. It is adequate for a simple read-only list operation, but not 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?

With 0% schema description coverage, the description must compensate for the undocumented 'source' and 'environment' parameters. It partially does by mentioning live environments and offline solution zips/folders, but it never explicitly maps those values to the parameter names or defines accepted formats/defaults, leaving the agent to infer the parameter semantics.

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

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

The description identifies the resource (canvas apps) and the two scopes it operates on: live environment and offline solution zip/unpacked folder. It also lists the return fields for each scope. However, it never explicitly states the verb 'list', relying on the tool name, and it does not differentiate from closely related siblings like canvas_overview.

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

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

The description conveys context by distinguishing between environment-based and offline/folder-based canvas apps, implying when each source path is relevant. It does not provide explicit when-to-use guidance, exclusions, or mention alternative tools such as canvas_overview or list_controls.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful context about the output structure (control tree with specific fields) and the substring matching behavior for control_type. However, it doesn't disclose details like pagination behavior, the meaning of 'limit', or what happens when no controls match. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single, information-dense sentence that front-loads the core purpose and output fields, then adds the optional filters and a pointer to the sibling tool. Every clause earns its place with no wasted words.

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

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

For a read-only list tool with annotations covering safety, the description covers the core purpose, filters, and output fields. However, it doesn't explain the 'source' parameter (which is required), the 'limit' parameter's behavior, or the 'app' parameter. Since the schema provides no descriptions for these, an agent may not know what 'source' refers to. This is a notable gap for a required 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 description coverage is 0%, so the description must compensate. It explains the 'screen' and 'control_type' parameters (including the substring behavior for control_type), but doesn't explain 'app', 'source', or 'limit'. The description adds some value for two of the five parameters, but the other three remain undocumented in both schema and description. This is a partial compensation, so a 3 is fair.

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

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

The description clearly states the tool lists a control tree with specific fields (name, type, variant, parent, depth, number of properties) and optional filters by screen and control type. It also distinguishes itself from get_control by noting that get_control is for formulas, which helps an agent understand the scope of this tool.

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

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

The description implies when to use this tool: when you need the control tree structure, optionally filtered by screen or control type. It explicitly points to get_control for formulas, providing a clear alternative. However, it doesn't explicitly state when NOT to use it or mention other alternatives like search_formulas, but the context is sufficient for most cases.

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 establish readOnlyHint and openWorldHint, so the description doesn't need to repeat those. It adds meaningful behavioral context: the listing covers all environments visible via global discovery, not just the current one, and includes an allowed/not-allowed marker that gates usage of other tools.

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 deliver the core purpose, scope, and a critical constraint. Every word earns its place, and the 'allowed' distinction is front-loaded in the second sentence where it matters.

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

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

For a zero-parameter read-only listing tool, the description is fully self-contained: it explains what is returned, the scope of discovery, and how the result should influence subsequent tool selection. No output schema is present, but the description compensates by describing the allowed/not-allowed marking.

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

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

The tool has zero parameters, so there is no parameter burden for the description to carry. The baseline of 4 applies; the description appropriately focuses on output semantics rather than input details.

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 ('list') and resource ('Dataverse environments'), with a clear scope: global discovery for the signed-in account. It adds the key detail that each environment is marked allowed/not allowed, which distinguishes its purpose from the sibling tools that operate within a single environment.

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 clearly implies this is the discovery/listing tool to use before other environment-specific tools, and explicitly states that only allowed environments can be used by the other tools. It does not name alternates or exclusions explicitly, but the context is strong enough for an agent to know when to call it.

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

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

Annotations already establish read-only and open-world behavior, so the description's added detail about relationship kinds (referenced/one side, referencing/many side, lookup column, cascade delete, intersect table) is valuable behavioral context beyond the annotations. It does not contradict annotations.

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

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

The description is a single dense sentence with no filler. It front-loads the core purpose, and the extra details are relevant. The parenthetical structure makes it slightly harder to parse, but it remains efficient.

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

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

There is no output schema, so the description must explain what is returned—it does at a high level. However, with three parameters and zero schema coverage, the missing meanings of source and app are significant. The description is not complete enough for an agent to invoke the tool correctly without additional 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%, so the description must compensate for parameter meaning. It explains only the table parameter ('limits to relationships touching that table') but leaves the required source parameter and the optional app parameter unexplained. An agent cannot reliably know what values to pass for these fields.

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 (list) and the resource (table relationships) and specifies the meaning: one-to-many and many-to-many relationship metadata. It is easily distinguished from siblings like list_tables, describe_table, and fetch_query.

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

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

The description implies when to use the tool: when you need relationship metadata from a solution or a canvas app's cached schema. However, it does not explicitly mention alternatives, exclusions, or when NOT to use this tool compared to related siblings.

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

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

The description adds meaningful behavior beyond the readOnlyHint/openWorldHint annotations: managed solutions are hidden unless include_managed=true and name_filter is a case-insensitive substring. This discloses default visibility and filter behavior without contradicting the annotations.

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

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

Two dense sentences; the first lists output fields and the second covers the two non-obvious parameters. There is 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?

For a read-only list tool with optional filters and readOnlyHint/openWorldHint annotations, the description covers the operation, visible data, and key filtering behavior. The main gaps are lack of output schema details and no explicit guidance on how to specify the environment or handle pagination/ordering.

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 name_filter (case-insensitive substring on unique or display name) and include_managed (reveals managed solutions), but leaves the environment parameter effectively unexplained beyond 'allowlisted environment'.

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 ('solutions') and enumerates the returned fields (unique name, display name, version, managed flag, publisher), making the operation concrete. It is clearly distinct from sibling tools that list other resource types or operate on a single solution.

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 offers no guidance about when to choose this tool over related siblings such as solution_components, export_solution, or diff_solutions. It explains filter and include_managed behavior, but that is parameter usage, not tool-selection 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?

Annotations already provide readOnlyHint=true and openWorldHint=true, covering the read-only nature. The description adds meaningful context: it mentions FetchXML usage, the lack of live column metadata in pac, and the dependency of describe_table on a source. No contradictions with annotations. It doesn't discuss limits or pagination, but that is a minor gap given the annotations.

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

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

The description is reasonably concise, front-loading the core purpose and then elaborating on the two modes and the pattern filter. It could be slightly more compact but avoids unnecessary fluff and is well-structured for an agent to parse.

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 six parameters, no output schema, and zero schema descriptions, the description covers the essential mode distinction and the pattern parameter but fails to explain the remaining parameters. An agent might invoke it correctly for basic usage, but the lack of detail on limit, custom_only, app, and environment creates ambiguity. The description is helpful but not 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 carries the burden. It clarifies 'source' (solution zip/folder or canvas .msapp/SourceCode folder) and 'pattern' (substring on logical or display name). However, it leaves 'app', 'limit', 'custom_only', and 'environment' unexplained, forcing the agent to infer their meanings from names and defaults.

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

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

The description clearly states the verb 'list' and resource 'Dataverse tables', and precisely distinguishes two modes (with/without source) and what each returns. It explicitly mentions the pattern filter and differentiates from describe_table by noting it needs a source, making the tool's purpose unmistakable.

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

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

The description implies when to use this tool: with source for cached app tables and without source for live environment names. It also hints that describe_table is needed for column metadata, but does not explicitly enumerate alternatives or exclusions for other siblings. The guidance is clear enough for basic selection.

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

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

The description goes well beyond the annotations. It discloses that dry_run is the default and returns a plan/command plus warnings, that execution requires allow_writes=true (implying a write operation), that nothing is sent to an environment, and that the default output path is <output>/packs/. It also mentions specific warnings (canvas data sources Studio would prune, empty DatabaseReferences). These are valuable behavioral insights not present in the annotations, and there is no contradiction.

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

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

The description is three sentences, with the core purpose front-loaded and every sentence adding new information. No fluff, no repetition. It packs a lot of relevant detail into a compact form, making it efficient for an agent to parse.

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

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

For a tool with 5 parameters and no output schema, the description covers the critical aspects: the local-only nature, the dry_run default and its return value, the need for allow_writes, the default output location, and even warning types. It does not explain the return value for actual execution (only for dry_run) and leaves package_type and overwrite behavior undocumented. These are secondary, so the description is quite complete but not perfect.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain dry_run in detail and indirectly mentions zip_path via the default output location. However, it does not explain the remaining parameters: folder (though obvious from context), overwrite, and package_type. The package_type default 'Unmanaged' and the meaning of overwrite are left undocumented. Given the 0% coverage, this is a moderate gap; the description adds some meaning but not enough for a fully informed call.

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 starts with a specific verb-resource pair ('Pack an unpacked solution folder into a solution zip') and names the underlying command (pac solution pack). It also distinguishes the tool from environment-touching siblings by stating 'Local only: nothing is sent to an environment.' This is clear, distinct, and immediately actionable.

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

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

The description explains the primary use case (packing locally) and the dry_run behavior, which implies when to use dry_run vs actual execution ('dry_run=true (default) returns the plan...'). It does not explicitly name alternatives (e.g., export_solution, import_solution) or state when not to use this tool, but the local-only constraint and the pack/unpack pairing with unpack_solution provide enough context. A slight deduction for not explicitly routing to a sibling when appropriate.

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

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

Annotations already provide readOnlyHint=true, and the description adds useful behavioral context beyond that: it confirms the tool performs no environment contact and covers local setup diagnostics. This is meaningful additional transparency for a triage 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?

Three short, information-dense sentences with no fluff. The main purpose is front-loaded, followed by usage guidance and a key behavioral constraint.

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

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

For a zero-parameter read-only diagnostic tool, the description is complete: it states what it checks, when to run it, and what it does not do. No output schema is needed to make the invocation behavior clear.

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 parameters, so the schema fully covers parameter semantics and the baseline is 4. The description does not need to explain parameter behavior and does not introduce any confusion.

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 begins with a specific verb and resource ('Check the setup') and enumerates exactly what is checked: config items, pac CLI version, and auth profiles. It also distinguishes the tool by noting it does not contact an environment, separating it from sibling tools like list_environments.

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

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

The description explicitly says 'Run this first when anything fails,' giving clear when-to-use guidance. It also implies when not to rely on it by stating it does not contact an environment, but it does not explicitly name alternative tools or exclusion scenarios.

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

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

Annotations already establish non-read-only, idempotent, non-destructive behavior. The description adds useful behavioral detail beyond those hints: the dry-run returns a verified target/command, and execution is gated on allow_writes=true. This helps an agent understand the tool's safety workflow without contradicting the annotations.

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

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

Two sentences carry the core action, the prerequisite, the default behavior, and the distinction between verification and execution. There is no filler, and the most important usage guardrail is front-loaded.

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

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

The description covers the tool's main workflow and safety gate, but it leaves notable gaps: the environment parameter is undefined, allow_writes is referenced but not exposed in the schema, and the result of an actual publish (dry_run=false) is not described. With no output schema and a non-trivial publish operation, this is adequate but not 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 must compensate for both parameters. It does explain dry_run's role and default well, but it does not clarify what values environment should take or how allow_writes (mentioned in the description but absent from the schema) is supplied. The compensation is partial rather than complete.

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 ('Publish all customizations') and the resource ('in an allowlisted environment'), and it maps to the known pac solution publish command. It is distinct enough from the sibling tools like pack_solution and import_solution that its purpose is understandable, though it doesn't explicitly contrast itself with 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?

The description gives concrete usage context: dry_run=true is the safe default that verifies the target and command, while actual execution requires allow_writes=true and dry_run=false. It doesn't name alternatives or state when not to use the tool, but the workflow 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.

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

Even with readOnlyHint=true, the description adds meaningful behavior: code_only ignores matches inside string literals/comments, property and control narrow the search, and results include control, property, and matching lines. It does not contradict the annotations.

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

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

Three compact sentences deliver the core purpose, key flags, filters, and return shape with no filler. The most important usage facts are front-loaded and 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?

For a 9-parameter tool with no output schema, the description covers the search/filter model and return fields, but the required source parameter is never explained and there is no guidance on limit or case_sensitive. That leaves enough ambiguity that an agent could mis-invoke the tool despite the strong overall framing.

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 carry the parameter-documentation burden. It explains regex, code_only, property, and control, and implies pattern is the search term, but it leaves required source and app undefined, and does not describe limit or case_sensitive. This is only partial compensation.

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 action and resource: 'Search every Power Fx formula in a canvas app' for a substring or regex. It also names the return shape (control, property, matching lines), making the tool's purpose unmistakable and distinguishing it from the sibling tools like list_controls and get_control.

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

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

The description provides clear operational context: regex toggling, code-only filtering, property filtering, and control filtering. It does not explicitly name alternative tools or state when not to use it, but none of the siblings are formula-search tools, so the intended use is clear.

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

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

It discloses the cloud upload, the fact that nothing changes in the environment, the wait/duration, and where output is written. This is valuable context beyond the raw annotations (readOnly=false, destructive=false) and aligns with them.

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 dense sentences front-load the operation and resource, then add only high-value operational details: cloud call, no environment change, duration, and output path. There is no filler or repetition of schema 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?

The operational lifecycle is well explained for a moderately simple tool, but with no output schema and 0% schema parameter coverage, geo and environment remain unclear. An agent can probably call it with just zip_path, but would be guessing about optional parameters and the exact return shape.

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

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

Schema description coverage is 0%, and the description only implicitly maps 'solution zip' to zip_path. geo and environment are left undefined, and there is no mention of defaults or whether they affect the checker service endpoint, so the description does not compensate for the sparse schema.

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

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

The description names a specific verb ('Run'), the exact resource ('solution zip'), the underlying command ('pac solution check'), and the outcome ('summarizes SARIF results by rule and severity'). This is enough to separate it from siblings like app_checker_results, which is about viewing results rather than running a check.

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 clearly implies the tool is for checking a solution zip and explicitly warns that it takes several minutes, which an agent should consider before invoking. It does not explicitly name alternatives or state when not to use it, so it stops short of a perfect score.

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

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

Annotations already signal readOnlyHint and openWorldHint. The description adds valuable behavioral detail: offline mode returns manifest fields, root components, and missing dependencies; live mode returns per-type rows with resolved names versus object IDs. This exceeds what annotations alone convey.

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, well-labeled with Offline/Live, and each clause adds substantive information. The only mild weakness is the opening phrase 'What a solution contains,' which restates the tool 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?

Despite the absence of an output schema, the description gives substantial return-value detail. However, it omits the meaning of 'environment,' potential error cases, and any preconditions, so it is not fully complete for a 3-parameter 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?

The input schema has 0% description coverage, so the description must carry parameter meaning. It clearly defines 'source' and 'solution' but never explicitly explains the 'environment' parameter, leaving one of the three parameters ambiguous.

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 what the tool reports—the components contained in a solution—and distinguishes offline (source) and live (solution) modes with concrete output details. It does not use an explicit action verb like 'lists,' but it is far from a tautology.

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 maps usage to parameters: use 'source' for a solution zip/folder and 'solution' for a live unique name. It does not compare against sibling tools or state when not to use it, but the offline/live distinction gives clear context.

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

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

Beyond the annotations, the description adds useful behavioral details: it creates a new folder under the output dir, returns that folder, and is local-only. It does not cover edge cases like existing folders or failure modes, but it is consistent with destructiveHint=false and openWorldHint=true.

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

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

The description is compact and front-loaded: the core action appears first, followed by the output path and the return-value usage. Every sentence carries useful information with no filler or redundant restatement.

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

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

Given there is no output schema, the description's mention of the returned folder and its role as source= is important and well provided. It does not detail prerequisites or the exact output directory base, but the description is sufficient for a simple two-parameter tool with strong sibling 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?

Though schema description coverage is 0%, the description compensates by tying zip_path to 'solution zip' and folder_name to the <output>/unpacked/<folder_name> path. This gives both parameters meaningful semantics beyond their bare titles. It does not explicitly restate folder_name's optionality, but the schema already exposes the default.

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

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

The description clearly states the verb 'Unpack' and the resource 'solution zip', including the underlying command (pac solution unpack) and local-only scope. It also specifies where the output goes, making the tool's function unambiguous and distinct from siblings like pack_solution or import_solution.

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

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

The description gives clear usage context: it is local-only and produces a folder that can be used as source= for offline tools. It does not explicitly name alternatives or state when not to use it, but the practical workflow context is strong enough for an agent to route 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: it fails with instructions when the sign-in has expired, and its environment selection defaults to the first entry in the allowlist rather than the schema's literal `default: ""`. These are exactly the operational details an agent needs. No contradiction with annotations (read-only aligns with a whoami-style query).

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

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

Three sentences, each earning its place: purpose, failure behavior, and parameter semantics. No filler or repetition of schema/annotation content. Slight deduction for the awkward, fragment-like first sentence ('Who pac is signed in as...') and the minor punctuation/formatting quirks, but overall it is tight and well-ordered.

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?

This is a simple tool — one optional parameter, no output schema, no nested objects — and the description covers purpose, the key failure mode (expired sign-in), and parameter semantics. The only real gap is that with no output schema, the return shape is never described, but for a whoami-style tool the output is predictable enough that this is a minor omission rather than a blocker.

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 for the `environment` parameter, and it delivers: it explains the value domain (URL or id), the source (the allowlist), and the effective default (first from allowlist) — which usefully corrects the misleading `default: ""` in the schema. It doesn't fully specify URL/id format or how to discover the allowlist, so a 5 is not warranted.

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 purpose: reporting which identity PAC is signed in as and which org it reaches within an allowlisted environment, with the `pac env who` mapping. This is clear and distinct in intent from siblings like list_environments (which lists environments, not identity) and pac_status (tool status). It earns a 4 rather than 5 because it never explicitly names a sibling or states the demarcation line, and the phrasing of the first sentence is somewhat awkward.

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 context is implied rather than explicit: the tool answers 'who am I / which org am I reaching' before working in an allowlisted environment. It provides parameter-level guidance (environment = URL or id from the allowlist, default first) but gives no when-to-use vs. alternatives guidance, no exclusions, and no mention of when pac_status or list_environments would be the better choice. This matches '3=implied usage'.

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