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 explicitly discloses read-only behavior, what is never done ('never writes files, loads hooks, reads auth or executes native CLI/live checks'), what is returned ('builder guidance, findings and explicit limitations'), and a concurrency caution ('Prevent concurrent filesystem mutation').

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

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

Front-loads the core purpose and is generally efficient, but has mild redundancy between 'partial static diagnosis' and the later 'never writes... executes native CLI/live checks'. The final fragment 'Prevent concurrent filesystem mutation' is a bit terse and could be clearer.

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 one parameter, no output schema, and no annotations, the description covers purpose, limitations, return contents, and side-effect boundaries well. It leaves some ambiguity about what 'findings' and 'builder guidance' look like, but that is reasonable without an output schema.

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

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

The single parameter workspaceRoot has 100% schema description coverage ('Canonical absolute mcdev project root.'). The description adds no parameter-specific meaning beyond the schema, which is the baseline for high schema coverage.

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 ('diagnosis') and resource ('.mcdevrc.json'), and explicitly scopes it as 'partial static' and 'not native mcdev validation or execution readiness'. This distinguishes it from raw config reads and from command execution 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?

Provides clear context for use: 'FIRST use the visual MCDev Pipeline Builder before editing configuration' and reinforces it is not for native validation or execution readiness. However, it does not explicitly compare against sibling tools like read_mcdev_project_config or preview_mcdev_project_config, leaving some routing ambiguity.

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

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

Goes far beyond the readOnly/openWorld/destructive annotations: it discloses exactly what is read (bounded project/logs timestamp files, never error companions or auth/session content), what is excluded (no subprocess, network, native execution, elicitation, rerun), and what is returned (finite observations and basename/time provenance, never raw logs, paths, errors, secrets). It also flags the --noLogFile no-log case and unknown-record suppression, which an agent could not infer from 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?

Purpose and scope are front-loaded in the first sentence, and every clause carries constraints or exclusions rather than filler. However, several sentences are densely semicolon-packed run-ons (the window/format sentence crowds five restrictions together), making it harder to scan than it needs to be.

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-output-schema, seven-required-parameter diagnostic tool, it covers the essentials: quiescence, window bound, selector syntax, negative-evidence semantics, and the shape of the result ('finite observations and validated basename/time provenance'). The main residual gap is that the structure of those 'observations' is never characterized, so the agent must call blind on 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?

With 0% schema description coverage, the description has to carry all seven parameters and it mostly does: it pins credential/businessUnit to 'one exact configured' value, constrains metadataType to canonical retrieve query/script keys, and defines the startedAfter/startedBefore pair as a UTC ISO millisecond window of at most 24 hours. It also warns against options, aliases or quotes in selectors. workspaceRoot is never mentioned and exact key format is only implied, so it is not fully compensatory.

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

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

Opens with a specific verb+resource: 'Read-only historical normal-log diagnosis for one exact configured credential/businessUnit and query or script key.' That is precise enough to distinguish it from run_mcdev_command and reconcile_mcdev_operation, which operate on live operations rather than historical log files. It stops short of explicitly naming which sibling to prefer, keeping it at 4.

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 real usage constraints: 'Requires caller-managed quiescence' and 'absent evidence is no-match, not a reason to repeat retrieval', plus 'investigate manually when evidence is insufficient'. These tell the agent when this tool applies and when to stop, but no sibling tool is named as an alternative for those 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?

With no annotations, the description carries the full burden and does so: read-only, no persistence, no branch/commit/history/auth/artifact reads, no native execution, ancestry based on a stale local remote-tracking snapshot, unknown remote BU synchronization, and non-atomic with a concurrency caveat. That is unusually rich disclosure of exactly the traits an agent needs before relying on results.

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?

It is front-loaded and every clause is arguably substantive, but the writing is a dense chain of negations and internal jargon ('top-level verified covers status metadata only; refs.verified is independent'), making it hard to parse on a first read. Tighter grouping of scope, limitations, and concurrency would improve it.

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

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

Given no annotations, no output schema, and one parameter, the description supplies scope, non-goals, staleness of ancestry data, partial verification semantics, and concurrency constraints. What it still omits is any hint of the shape of the returned metadata beyond vague mentions of 'verified' and 'refs', which would help the agent interpret the output.

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

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

There is a single required parameter with 100% schema description coverage ('Canonical absolute mcdev project root'), so the schema already does the work. The description adds no further meaning about workspaceRoot (e.g., what happens if it's not a Git repo or not canonical), which fits the baseline 3 for full schema coverage.

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

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

Opens with a specific verb+resource: 'Read-only Git metadata inspection', and explicitly separates itself from inspect_mcdev_project's auth protection checks, so it's distinguishable from the nearest sibling. However, the purpose is buried inside a string of caveats rather than stated as a clean sentence about what Git metadata is returned (status, refs, ancestry), which keeps it below 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 draws one boundary ('Separate from inspect_mcdev_project auth protection checks') and warns to avoid concurrent project/Git mutation, which implies when it's appropriate. But it never says positively when to call this tool, nor names alternatives like inspect_mcdev_git_range, which most agents would need to disambiguate between the two Git inspection 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?

With no annotations, the description carries the behavioral burden and does so well: read-only, local snapshot only, unknown remote freshness/BU sync, no auth/log/artifact/commit-content reads, no branch changes or execution, and a concurrency/atomicity warning. These are concrete operational limits an agent needs before calling.

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

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

The opening sentence front-loads the core operation, and subsequent clauses are dense but purposeful for a high-risk inspection tool. Some negation-heavy fragments make it read like a checklist, but there is little outright waste.

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

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

The description is rich on scope, exclusions, and operational limits, which is important given no annotations. However, with no output schema, it never explains what the comparison returns—what metadata, containment result, or shape an agent should expect—so it is not fully complete for a tool whose output is central.

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 100%, so the schema already documents all four parameters; the description still adds value by explaining declaredEdge semantics—it assesses only exact-source-commit containment and preserves source-to-target direction even for back-promotion. That is meaningful beyond the enum and required params.

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 'Read-only Git metadata comparison of two explicit refs,' a specific verb and resource, and immediately scopes it away from promotion policy or execution readiness. The final clause distinguishes it from inspect_mcdev_project auth checks and implies separation from git policy, so an agent can route correctly.

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

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

Explicitly says what it is not for ('not promotion policy or execution readiness') and separates it from inspect_mcdev_project auth protection checks, giving useful when-not context. It stops short of naming inspect_mcdev_git_policy as the alternative for policy checks and does not give a positive 'use this when...' trigger beyond the ref-comparison scope.

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

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

With no annotations, the description carries the burden well by disclosing read-only behavior and explicit non-actions: it never reads auth contents or history and never repairs, stages, or untracks files. It still omits permission requirements and return behavior, but the core safety profile is clearly stated.

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

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

The definition is two tightly packed sentences with no wasted language. The primary purpose is front-loaded, and the second sentence efficiently lists the read-only constraints.

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-output-schema inspection tool, the description gives a useful sense of what is read and what safety constraints apply. It could say more about the shape of the returned config/metadata, but it is largely complete for invocation.

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

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

There is one parameter and schema description coverage is 100%, so the schema already explains workspaceRoot as the canonical absolute mcdev project root. The description adds no parameter-specific meaning beyond what the schema provides, making 3 the appropriate baseline.

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

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

The description states a specific verb and resource: read the complete unredacted project config, including credentials, and inspect Git ignore/index metadata for auth protection. The word UNREDACTED implicitly distinguishes it from read/preview config siblings, but it does not explicitly name or route against those 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 implies when to use it: when full unredacted config and Git auth-protection metadata are needed. It does not explicitly say when to choose it over read_mcdev_project_config, preview_mcdev_project_config, or the git-policy inspection 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?

With no annotations, the description carries the full burden and does well: it discloses read-only/metadata-only behavior, no remote-freshness guarantee, no atomic sandbox, and warns to prevent concurrent filesystem mutation. Missing only error/failure behavior (e.g. what happens if workspaceRoot is absent or paths are unconfigured).

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-loaded with the capability and followed by limits, with no filler. The second sentence compresses several distinct caveats into one run-on clause, which slightly hurts scanability but wastes nothing.

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 inventory with no output schema, the description covers scope and behavioral caveats adequately, but leaves the agent guessing about the shape of the returned inventory and about what maxDepth/maxEntries actually control. Adequate, not 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 33% – only workspaceRoot is documented. The description adds nothing about maxDepth or maxEntries, both of which have non-obvious bounds (1-12, 1-10000) and unclear interaction with the walk. With low coverage the description should compensate but instead ignores two of three 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?

States a specific verb and resource: 'read-only, metadata-only inventory of configured retrieve/deploy paths.' It also draws a boundary against content-reading siblings by saying it 'does not open artifact contents', which separates it from read_mcdev_artifact_source and resolve_mcdev_project_artifact. It stops short of naming those alternatives 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?

The 'does not / never' clauses (no contents, no dependency confirmation, no auth, no logs) give clear negative guardrails, so an agent knows what this tool will not answer. However there is no positive statement of when to reach for it versus resolve_mcdev_project_artifact or read_mcdev_artifact_source.

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

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

No annotations exist, so the description carries the burden. It does disclose the return content (a checklist of questions plus dependent metadata types), which is the key behavioral fact and useful given there is no output schema. However, it says nothing about whether component keys are validated, what happens on an unknown key, or how dependency resolution is performed.

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 with the verb front-loaded and zero filler. Nothing could be removed without losing information.

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

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

For a one-parameter read tool with full schema coverage, the description is nearly sufficient, and it partly compensates for the absent output schema by characterizing the return value. It stops short of telling the agent how to discover valid component keys, which is relevant given the sibling list.

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 100% and the single `component` parameter is well documented, so the baseline is 3. The parenthetical examples ("journey, automation") merely repeat the schema's own examples and add no new 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?

Names a specific verb ("Return") and a concrete resource ("structured checklist of questions and dependent metadata types"), scoped to authoring/migrating SFMC components. It does not explicitly distinguish itself from siblings like mcdev_list_metadata_types, which also deals with metadata types, so an agent must infer the boundary.

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

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

The phrase "for authoring or migrating SFMC components" gives an implicit usage context, but there is no statement of when NOT to use it and no named alternative (e.g. use mcdev_list_metadata_types to enumerate valid keys). The agent is left to infer.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the return shape ('short summary and wiki file hints'), which is useful. It says nothing about permissions, rate limits, or whether explanations are static or project-aware, so gaps remain.

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 front-loaded sentence that states the action, the target, examples, and the output in a compact form. The example key list slightly duplicates the schema's known-keys list, which is minor redundancy.

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

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

For a single-parameter, read-only explainer with 100% schema coverage and no output schema, the description is nearly sufficient: it names the target concept space and what comes back (summary plus wiki hints). Only the relationship to sibling lookup tools is left implicit.

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 100% and the single 'topic' parameter already documents its known keys in the schema description. The description's parenthetical key list adds no semantics beyond the schema, so the baseline 3 applies.

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 (Explain) and resource (.mcdevrc.json concept) and gives concrete example keys, so the agent knows exactly what it returns. It does not explicitly differentiate from siblings like read_mcdev_project_config or mcdev_search_docs, which keeps it from a 5.

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

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

Usage is only implied: an agent can infer this is for learning what a config concept means, as opposed to read_mcdev_project_config (reads an actual project's values) or mcdev_search_docs (free-text docs search). No explicit when-to-use or when-not-to-use statement is 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 full burden and does so: it declares read-only behavior, no side effects (no approval, no process launch, not a dry run), and flags that project readiness is unverified. It also discloses the returned fields, which matters since there is no output schema.

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

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

Four short sentences, front-loaded with the core identity before caveats. Every clause carries information, though the final 'Project readiness remains unverified' is terse enough to be slightly ambiguous without supporting context.

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

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

For a one-parameter lookup with no output schema, the description covers purpose, return content, safety profile, and next-step routing. Nothing an agent needs in order to call it correctly appears to be missing.

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

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

Schema coverage is 100%, so the single parameter is already documented, giving a baseline of 3. The description adds meaningful nuance by stressing 'exact' and 'case-sensitive' lookup semantics beyond the schema's wording, though it does not explain lookup failure behavior for near-matches.

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 ('exact, case-sensitive native command or alias lookup') plus what is returned (signature, execution availability, effects). This clearly separates it from sibling tools like mcdev_list_commands (enumeration) and run_mcdev_command (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?

Explicitly routes the agent: use the canonical name with run_mcdev_command once supported, and the lookup itself grants no approval, launches no process, and is not a dry run. This names the alternative and the condition that selects it, leaving little to inference.

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

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

With no annotations provided, the description carries the burden and discloses important behavior: it returns a JSON page with UTF-16 offsets and nextOffset null at the end, and retrieved claims are not endorsements. It does not cover auth or rate limits, but for a retrieval tool the key return and pagination behavior is documented.

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, followed by return and pagination details. Every clause contributes useful information without redundancy.

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

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

No output schema exists, so the description must explain the return value; it does so by describing the JSON page, offsets, and end-of-pagination signal. With complete parameter schema coverage, this is sufficient for correct invocation, though explicit error behavior is not covered.

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 100%, with id, limit, and offset all fully described in the input schema. The description adds little beyond identifying id as a Source ID from search, so the baseline of 3 is appropriate when the schema does the detailed work.

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

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

The description states a specific verb and resource: retrieve a bundled wiki section by its search Source ID. It also notes the section is unreviewed, which helps distinguish this retrieval tool from search and review-oriented siblings.

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

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

The phrase 'by its search Source ID' gives clear usage context: this tool is a follow-up to mcdev_search_docs. It does not explicitly name alternatives or exclusions, but the prerequisite is clear enough for an agent to select it correctly.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that the operation is read-only, performs no subprocess or dry run, notes there is no native mcdev dry-run mode, and clarifies that project readiness is not verified. These are substantive behavioral traits beyond what structured fields provide.

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 four sentences, front-loaded with the core purpose and then adding usage contrast and behavioral caveats. Every sentence contributes useful information without padding.

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 zero parameters, no output schema, and no annotations, the description is complete enough: it states the return-ish content (signatures, aliases, execution availability and effects), clarifies what listing does not do (no subprocess/dry run), and notes the project-readiness limitation. Nothing critical is missing for an agent to call it correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately does not waste space on parameter semantics when none exist.

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

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

The description states a specific verb and resource ('Read-only native mcdev command discovery: signatures, aliases, execution availability and effects'), making the tool's function clear. It distinguishes itself from the execution sibling (run_mcdev_command) but does not explicitly differentiate from mcdev_get_command, which likely retrieves a single command.

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 names the execution alternative ('Use run_mcdev_command for supported commands with explicit arguments and ordinary host approval'), giving clear context for when to use that tool instead. However, it does not explicitly state exclusions for single-command retrieval (mcdev_get_command) or other discovery tools, leaving some alternative routing 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?

No annotations are provided, so the description carries the full burden. It usefully discloses that the list is derived from the installed package (Mcdev.explainTypes), meaning results vary by version, and 'List' implies a read operation. It does not state return shape, ordering, or whether the result is exhaustive.

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 compact sentence that front-loads the action and resource, with the optional filter noted at the end. No filler, nothing redundant.

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

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

For a no-required-param, read-only listing tool with full schema coverage, the definition plus source provenance is nearly sufficient. The one omission is any hint about what the returned type entries look like, which matters slightly since no output schema exists.

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

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

Schema description coverage is 100%, so the schema already documents the filter as 'Case-insensitive filter on name or apiName.' The description's 'Optional filter substring' merely restates this at a higher level and adds no new syntax or matching detail. Baseline 3 applies.

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

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

Specific verb+resource: lists metadata types, and identifies the data source (installed mcdev package / Mcdev.explainTypes). An agent can distinguish it from search_docs or explain_config_key, though it never explicitly names a sibling to sharpen the contrast.

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

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

No when-to-use guidance, no prerequisites, and no alternatives named among the four sibling tools. The agent must infer that this is the discovery step for available metadata types before other mcdev operations.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does usefully disclose the corpus origin (bundled Markdown sourced from the GitHub wiki), implying local/offline retrieval and possible staleness, but says nothing about ranking, snippet format, or freshness relative to the live wiki.

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

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

A single front-loaded sentence with the verb and corpus stated first, followed by the topical scope. No filler, though the trailing keyword list reads more like tags than prose.

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

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

Adequate for a two-parameter search tool, but with no output schema and no annotations the description leaves the return shape (file paths? snippets? scores?) unstated and gives no hint about result freshness or whether the query supports multiple keywords. Minimum viable rather than 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 100%, so both parameters (query, limit with default 8 and max 25) are already documented in the schema. The description adds only topical keyword hints for what a query should contain; baseline 3 applies when the schema does the heavy lifting.

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 (Search) and a precisely bounded resource (bundled sfmc-devtools wiki Markdown from GitHub wiki), plus the topical coverage: configuration, commands, markets, createDeltaPkg, build, validations. This scope makes it distinguishable from topical siblings like mcdev_explain_config_key, though no sibling is named 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?

The topic list implies when the tool is useful (questions about mcdev config, commands, build/validation), but there is no explicit when-to-use vs. when-not guidance and no routing to alternatives such as mcdev_explain_config_key for single-key questions. Usage is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it explicitly states read-only, guidance-only, no subprocess/hooks/auth-log reads/live checks, execution disabled, cannot authorize. It does not describe what the tool actually returns or whether it reads files, but the negative behavioral profile is unusually thorough.

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 key safety profile, but it is a dense, repetitive paragraph of mostly negative clauses. Sentences like 'Generic native effects are not proven project-local effects' are abstract, and 'Prevent concurrent filesystem mutation' is unclear in context.

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

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

For a 7-parameter tool with a nested options object and no output schema, the description is incomplete on the positive side: it never explains what the preview returns, what 'guidance-only' concretely means, or how to interpret the result. It also provides no sibling differentiation, leaving an agent without enough to call it confidently.

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 86%, so the schema already documents most parameters (including options) well. The description adds no parameter-specific meaning beyond what the schema provides; it only references credential/businessUnit mapping, which is already 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?

The description states a specific verb and resource: a 'retrieve/deploy preview' for an mcdev project, qualified by credential/businessUnit. It distinguishes itself from execution ('Not a dry run', 'execution remains disabled'), but it does not name or differentiate from siblings like run_mcdev_command or preview_mcdev_project_config.

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

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

Usage is implied: call this to preview a retrieve/deploy command before execution, and it only verifies credential/businessUnit mapping. There is no explicit when-to-use vs alternatives, no prerequisites stated, and no exclusions beyond 'execution remains disabled'.

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

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

With no annotations, the description carries the full behavioral burden and does so: it discloses no writes/apply authorization/native validation, no auth/logs/hooks/live checks, concurrency caution, input size caps, UTF-8 hashing semantics, and byte-budgeted output. This is unusually complete for a preview 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 purpose is front-loaded and most clauses are substantive, but the single dense paragraph piles caveats with semicolons and some legalistic phrasing ('native validation, execution readiness or atomic filesystem binding') that is harder to parse than necessary. It is still appropriately sized for a high-complexity read-only preview tool.

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

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

No output schema exists, and the description nevertheless explains the return shape enough (full unredacted changes plus partial static proposed diagnosis within a byte budget), input limits, safety boundaries, and concurrency expectations. An agent has enough to decide and call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3; the description reinforces 'complete document, not a patch' and the 1 MiB input cap but adds little parameter meaning beyond the schema. Hash semantics are output-related, not 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 first sentence names a specific verb (read-only comparison) and both resources (.mcdevrc.json and a complete proposed JSON document), and rules out a patch. It does not name or route against sibling config tools such as read_mcdev_project_config or diagnose_mcdev_project_config, so sibling differentiation 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?

It gives workflow context ('before editing configuration') and a prerequisite to use the visual builder first, plus non-goals, but it never states when to call this versus read_mcdev_project_config or diagnose_mcdev_project_config. Usage is inferable as a preview-before-edit check, not explicitly prescribed.

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

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

With no annotations, the description carries the full burden and does so thoroughly: returns complete original UTF-8 text including BOM plus SHA-256 of original bytes, no truncation, unresolved or blocked results never contain source, no rendering/validation/mutation/live execution, execution readiness unknown, bounded checks are not atomic against concurrent filesystem mutation, and auth contents and logs are never read. These are non-obvious safety and output-shape facts an agent could not infer from schema or 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?

Nearly every sentence carries real information and the read-only/no-source-on-failure constraint is front-loaded, but the delivery is a dense run-on of fragments and negations that is hard to parse on first read. It would benefit from grouping output shape, blocking rules and validation handoff into separate statements.

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, no-annotation, no-output-schema tool, the description covers output format, failure behavior, blocking rules, safety limits and the validation handoff the host must perform. The remaining gaps are the seven undocumented parameters (identity, root, credential, bounds) that an agent must resolve purely from schema.

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

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

Schema description coverage is only 22% across 9 parameters, and the description meaningfully explains sourceRole semantics (resolved email companions only, no arbitrary filenames or paths) and constrains metadataType to bounded htmlemail/templatebasedemail layouts. But workspaceRoot, rootKind, credential, businessUnit, externalKey, maxDepth and maxEntries receive no explanation anywhere, so the description only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('read-only full-text editable-source handoff for one qualified query, script or bounded asset-email identity') and enumerates the metadata types, and it explicitly distinguishes itself from path-based readers ('never a caller-supplied file path'). The phrasing is dense and jargon-laden, but an agent can tell what it retrieves and what it does not.

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

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

Gives concrete use conditions and blockers: exactly one editable companion required, multiple companions need an explicit sourceRole or are blocked, sourceRole applies only to resolved email companions, email html requires validate_sfmc_html, SQL validation not established. It routes the agent toward validate_ssjs/validate_sfmc_html/validate_ampscript, though it names them as capabilities to discover rather than as named sibling tools.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses that credentials are included, that raw text is returned, and that `.mcdev-auth.json` is never read. It does not describe failure behavior if the file is missing or inaccessible, which prevents 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?

Two tightly written sentences with no waste. The key distinction—unredacted output—is front-loaded, and the auth file exclusion follows immediately.

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 simple one-parameter read tool with no output schema, the description covers return format and scope sufficiently. It would be stronger if it mentioned behavior when the config file is absent or unreadable, but no critical decision information is missing.

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

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

Schema coverage is 100% and the single `workspaceRoot` parameter is already documented as an absolute path to the mcdev project root. The description reinforces 'canonical absolute project root' but adds no syntax or validation details beyond 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?

The description states a specific verb (read) and resource (`.mcdevrc.json`), and distinguishes this from the auth file explicitly. It also specifies the scope: complete, unredacted contents, raw text, from a canonical absolute project root.

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 makes clear when this tool is appropriate: when the full unredacted config is needed. It does not explicitly name the sibling alternatives such as `preview_mcdev_project_config` or `diagnose_mcdev_project_config`, but the 'UNREDACTED' framing strongly implies the distinction.

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?

Goes well beyond annotations by enumerating what the call does NOT do — no reconciliation, no process killing, no retry, no authorization of a new operation — which prevents the agent from over-trusting it as a recovery action. This is exactly the kind of caveat structured fields cannot carry, and it is consistent with readOnlyHint=false/destructiveHint=false (a state-clearing acknowledgement, not a destructive write).

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, front-loaded with what the tool does, then the negative scope, then the anti-pattern trigger. Every sentence adds a distinct constraint; nothing is redundant.

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

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

For a two-parameter acknowledgement tool with no output schema and annotations already declaring safety, the description covers safety, preconditions, and misuse well. It leaves gaps on the workspaceRoot scoping and on behavior when the acknowledgement is given prematurely or the latch is already clear (idempotency).

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

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

Schema description coverage is 0% for two parameters, so the description must carry the burden. It implicitly explains operatorReconciled (the operator must have confirmed), but never names either parameter and gives no guidance on workspaceRoot scoping. Partial compensation only.

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

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

States a specific verb ('Release') and resource ('an uncertain native-operation latch under operator acknowledgement') with the precondition baked in. The negative framing ('does not perform or verify reconciliation, kill processes, retry commands or authorize a new operation') distinguishes it from siblings like run_mcdev_command and preview_mcdev_project_command. Slightly opaque jargon ('native-operation latch') keeps it off a 5.

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

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

Gives an explicit positive trigger ('only after the operator has confirmed all related processes stopped and reconciled partial local/remote effects') and an explicit exclusion ('Never call solely because a server restarted or a timeout elapsed'). No inference required — the agent knows both when and when not to call.

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

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

With no annotations, the description carries the full burden and does substantial work: read-only, returns paths not contents, no dependency confirmation, blocked/ambiguous yields no editable companions, never reads auth or logs, no remote-freshness guarantee, no atomic sandbox. It omits error/edge behavior for invalid credentials or missing roots, but the disclosure is well above average for an unannotated tool.

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

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

The capability is front-loaded in the first sentence, but it is a dense multi-clause run-on packed with qualifiers ('bounded', 'companions', 'qualified') that slows parsing. Later sentences earn their place as constraints; the closing concurrency warning is useful but slightly tacked on.

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

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

No annotations and no output schema mean the description should clarify return shape and parameter meaning, but it only says 'returns paths' without structure, and five parameters remain undocumented. For an 8-param, 6-required tool this leaves real gaps an agent must guess at.

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 only 25%: metadataType and workspaceRoot are documented in the schema, and the description adds meaning for metadataType and hints at externalKey as customerKey matching. However, rootKind (retrieve/deploy), credential, businessUnit, maxDepth, and maxEntries are unexplained in both schema and description, leaving most of the 8 parameters opaque.

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 resource (local project artifacts) and enumerates the supported metadata types and layouts, then clarifies the output is paths rather than file contents. 'Qualified local resolution' is jargon-heavy, but the added sentence 'Returns paths, not arbitrary file contents' pins down the actual operation and implicitly separates it from read_mcdev_artifact_source.

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

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

It gives a clear exclusion ('other types and layouts are unsupported') and scope boundaries, but never names a sibling alternative or says when to prefer this over inventory_mcdev_project_artifacts or read_mcdev_artifact_source. The agent must infer the routing condition from the type list.

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?

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false) by naming the specific side effects (overwrite/deletion/auth-persistence), stating that deploy/runtime effects need a user request plus host approval, that no terminal interaction or auto-defaults occur, that diagnostics are bounded projections, and that partial/unknown operations must never be auto-retried. This is exactly the extra context annotations cannot express.

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

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

Purpose and the argv-vs-shell-string distinction are front-loaded, and nearly every sentence carries a distinct operational rule. The style is telegraphic and dense, and the timeout/progress sentence sits at the tail where it is easy to miss.

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 destructive, open-world tool with no output schema, the description covers side effects, consent/approval expectations, retry policy, and the nature of diagnostics. The remaining gaps are the meaning of workspaceRoot and timeoutMs, and where valid command values come from beyond a pointer to mcdev_get_command.

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 carry the load. It does well for args ('exact argv tokens after the canonical command, not a shell string') and partially for command (native mcdev command, consult mcdev_get_command), but workspaceRoot is never explained and timeoutMs is only obliquely referenced by 'Configure host timeouts for long operations' with no units or bounds.

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?

Names a specific verb+resource (execute a native mcdev command) and adds a scoping qualifier ('explicitly requested', 'developer-controlled project'). It distinguishes itself from mcdev_get_command, which it routes syntax lookups to, but never contrasts with the sibling preview_mcdev_project_command, which is the closest alternative for dry-run style invocation.

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

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

Explicitly directs syntax/availability questions to mcdev_get_command and states operational rules: 'Supply explicit target/choices; no terminal interaction or automatic defaults' and 'Deploy/runtime effects require the corresponding user request and ordinary host approval.' No explicit when-not-to-use guidance relative to preview_mcdev_project_command, so it stops short of a 5.

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