ALM X++ MCP Server

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

Annotations provide readOnlyHint=true, and the description builds on that with rich behavioral context: it reads changed-file content directly from the PR's source commit, embeds the FULL un-merged source when includeSource is true (one fenced block per file, trucated past sourceCharsPerFile), and explains why metadata-only PRs may show few BP violations. It also discloses auth needs (DEVOPS_ORG_URL + DEVOPS_PAT, Code: Read) and the side-effect-free workflow (produces a ready-to-post comment that a separate tool posts with user confirmation). Nothing contradicts the read-only annotation.

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 long but front-loaded with the PRIORITY TRIGGER block and every sentence carries operational directives an agent needs (triggers, exclusions, mechanism, edge case, workflow, auth). There is some redundancy — the NEVER/DO NOT git directives are re-iterated and the embedded-source benefit is stated twice — and the capitaliation-heavy style adds noise. Overall the length is justfied by 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 analysis tool with no output schema, the description defines what the agent gets back: BP Critical/Warning violations, upgrade impact cross-referencing CoC targets and event handlers, extension-conflict findings, embedded source, and a ready-to-post PR review comment adressed to the author. It also covers edge cases (metadata-only PRs, larger PRs summarized beyond maxFilesDeep), auth prerequisites, and the next tool to call. An agent has everything needed to select and invoke this correctly in one read.

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%: all 7 parameters (prId, repositoryId, project, maxFilesDeep, includeSource, includeWarnings, sourceCharsPerFile) carry their own schema descriptions, including defaults and behavioral notes. The tool description adds only marginal value beyond that — the 'one fenced block per file' formatting detail and a re-statement of the includeSource rationale. Since the schema already does the heavy liftng, 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?

The description names a specific verb and resource ('Analyse the full D365 F&O code impact of a Pull Request') and explicitly carves out the tool's scope: it reviews proposed un-merged code including brand-new files via the ADO REST API. It further distinguishes itself from search_d365_code and local git diffs, so an agent can tell what this tool is and is not. The only minor gap is that the similarly-named sibling ado_review_xpp_pr is never adressed, but the core purpose statement is unambiguous.

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

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

Guidance is exceptionally explicit: a literal trigger-phrase list ('analyse PR', 'review PR', 'PR #', 'D365 impact of PR'), a hard exclusion ('NEVER call search_d365_code when PR or Pull Request + a number is mentioned'), and an explicit prohibition on git fallbacks ('DO NOT fall back to local git show/git diff', 'NEVER run git'). It also routes the follow-up to ado_post_pr_comment with the user-confirmation requirement. The one omission is not routing to the sibling ado_review_xpp_pr, but the trigger list effectively decides selection for PR-review intents.

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?

readOnlyHint=true is consistent with the read-only verb 'Fetch' — no contradiction. The description adds meaningful behavioral context beyond the annotation: it returns raw structured context only (NOT a finished analysis), requires DEVOPS_ORG_URL + DEVOPS_PAT env vars, and imposes a post-call synthesis obligation on the agent.

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

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

Front-loaded with purpose, scope, and trigger phrases before any behavioral detail. The post-call Copilot instructions section is long but earns its place because the tool returns raw context and the agent needs the response contract; minor redundancy in the French section template (section descriptions + bullet elaborations) keeps it from a 5.

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 carries the return-value burden and discharges it fully: it enumerates 4 concrete return categories (metadata, KB object details, custom code, CoC relation graph). For a 6-parameter tool with heavy sibling overlap, nothing blocking is missing — triggers, exclusions, env prerequisites, return shape, and post-call behavior are all 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 description coverage is 100%, so the baseline is 3. Each of the 6 parameters already has a rich schema description with usage tips (maxComments cap 20, focusObjects speeds up analysis, includeImages costs latency/tokens), and the tool description itself adds no parameter-level detail beyond the env var requirement. The schema does the heavy lifting here.

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

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

States a specific verb + resource ('Fetch a Work Item and assemble ALL technical context needed for D365 F&O expert analysis') with an explicit platform boundary ('AZURE DEVOPS ONLY'). It differentiates from siblings by naming what it is not for and by defining its output as full context assembly rather than a simple query (which distinguishes it from ado_query_workitems).

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

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

Provides an explicit PRIORITY TRIGGER phrase list in both French and English, and an explicit NEVER-for clause with alternative tool routing ('use search_labels / search_d365_code instead'). It also states a hard exclusion: never call ado_post_comment on linked/related work items — only on the analyzed WI.

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

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

With no annotations available, the description carries full responsibility for behavioral disclosure. It does this thoroughly: it explains automatic branch creation, child/parent linking, related-work-item handling, auto-increment naming, assignee/CC embedding, language behavior, and required credentials/scopes. This far exceeds what the schema or annotations 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 long but dense and well-structured. It front-loads the WHEN/trigger section, then organizes the naming logic into clear rules (A/B/C), followed by branch, assignment, language, and credentials. Every sentence contributes actionable information; nothing is redundant filler.

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

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

For a complex mutation tool with 10 parameters, no output schema, and no annotations, the description is complete. It covers prerequisites, trigger conditions, naming conventions, branching behavior, assignee handling, language expectations, and required permissions. An agent has enough context to select and 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 covers all parameters with detailed descriptions, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially for workItemId (defining three parent-relationship scenarios and resulting task names/branches), repositoryId (branch creation), and assignTo/notifyList (embedded in description). Not every parameter is elaborated in prose, but the most consequential ones are.

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

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

The description uses a specific verb and resource: 'create a D365 F&O development Task work item in Azure DevOps'. It clearly distinguishes this from sibling tools by focusing on creation/starting development, with trigger examples. The naming convention and parent-relationship rules further make 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 gives explicit WHEN conditions and trigger phrases ('create task', 'start development on', 'créer une tâche'), which tells an agent when to select it. It also specifies the language rule and parent-based routing logic. However, it never explicitly says when not to use this tool or names alternatives like ado_update_workitem, so it stops short of a full when-not/alternatives 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 declare readOnlyHint=true, and the description adds useful behavioral context by explaining that the tool combines KB signals with ADO history and returns a phase breakdown, confidence level, and risk factors. It also notes the focusObjects parameter can speed up the estimate, which is beyond what the schema alone provides.

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 well-structured with clear sections (WHEN, PRIORITY TRIGGER, Returns, Triggers) and front-loads the core purpose. It is slightly redundant because trigger phrases appear both in the WHEN/PRIORITY TRIGGER section and in the final Triggers list, but the organized layout keeps it scannable and useful.

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 by explicitly listing return contents: per-phase hour breakdown, KB signals, confidence level, risk factors, and a paste-ready estimate. It covers key context like trigger conditions and sequencing with a previous analysis step. It does not describe error or edge-case behavior, but that is not critical for this read-only estimator.

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 each parameter already includes descriptive text (workItemId example, project fallback, focusObjects force-include behavior). The tool description adds little parameter-level meaning beyond the schema, so the baseline of 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?

The description opens with a precise verb and resource: 'Estimate D365 F&O development effort for a Work Item.' It clearly distinguishes itself from siblings by framing the output as a structured hour estimate with per-phase breakdown, not analysis, creation, or comment posting.

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 tells the agent when to call it ('WHEN: user asks for an effort estimate...'), gives the priority sequencing ('call AFTER ado_analyze_workitem'), and provides concrete trigger phrases such as 'estimate WI #N', 'how long for WI #N', and 'chiffrage WI #N'. This is explicit, actionable usage guidance.

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

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

With readOnlyHint=true, the description needs to add non-safety behavior context, and it does: it discloses the four classification outcomes, the detected domain, standard objects, extension lookup depending on D365_CUSTOM_MODEL_PATH, and the effort estimate with reasoning. There is no contradiction with the read-only annotation; the tool is clearly an analysis/classification operation.

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 well-sectioned and scannable, but it repeats trigger information in both the opening 'WHEN' block and the later 'Triggers' list. The emoji-laden verdict list is useful but adds verbosity. It earns a middle score: organized yet redundant in places.

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 carries the burden of explaining return contents; it does so explicitly by listing the detection domain, standard objects, extensions, effort estimate, and reasoning. It also covers input routing and environmental context for extension detection, making the tool sufficiently fully specified for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's role. The description adds extra semantic value by explaining parameter selection strategy, especially the rule to prefer requirementText over re-fetching workItemId after prior analysis, and that requirements overrides the other inputs. This goes beyond the baseline but still leans on schema for basic meaning.

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

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

The description opens with a clear WHEN clause and then states the core function: 'GAP / FIT CLASSIFIER -- Analyse a D365 F&O requirement... and classify it as one of four verdicts'. It lists the four verdicts explicitly (Standard Fit, Config Fit, Extension Fit, Gap) and describes what the tool returns, making its purpose unambiguous and distinguishable from sibling analysis tools.

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

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

The description provides explicit trigger phrases and concrete guidance on when to pass requirementText directly versus using workItemId, including a specific directive: 'do NOT re-fetch with workItemId' when a WI has already been analyzed by ado_analyze_workitem. This gives the agent actionable selection criteria beyond the schema.

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 read-only nature is covered. The description adds valuable behavior beyond that: omitting repositoryId lists all repositories first, requires DEVOPS_ORG_URL + DEVOPS_PAT with Code: Read scope, and summarizes the return fields. This adds meaningful context 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?

The description is fairly long but front-loaded with the PRIORITY TRIGGER and exclusion warning, followed by the core function, filters, return values, and prerequisites. Every section earns its place, though the long trigger list could arguably be trimmed. Overall it is dense but structured and 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?

With no output schema, the description compensates by listing the returned fields (PR ID, title, author, branches, review status, work items, creation date). It also covers triggers, exclusions, behavior, filters, auth requirements, and related tools. For a read-only listing tool, everything an agent needs to select and invoke it correctly is present.

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

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

Schema description coverage is 100%, giving a solid baseline of 3. The description adds value by summarizing the supported filters (status, author, target branch) and restating the repositoryId fallback behavior in natural language. This reinforces parameter meaning without duplicating every schema detail.

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: 'List Pull Requests in an Azure DevOps Git repository'. It clearly distinguishes itself from siblings by explicitly prohibiting search_d365_code for PR listing and by pointing to ado_analyze_pr_impact for impact analysis. An agent can immediately tell what this tool does and how it differs from similar tools.

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

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

A PRIORITY TRIGGER block lists concrete user phrasings that should route to this tool, and the description explicitly says 'NEVER call search_d365_code for PR listing requests'. It also names ado_analyze_pr_impact as the follow-up tool for impact analysis, giving clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It clearly warns that explicit user confirmation is ALWAYS required and states the permission prerequisite: 'DEVOPS_PAT with Work Items: Write permission.' It does not describe the return value or side effects beyond creating a comment, but the confirmation and permission details are significant and go beyond a basic mutation description.

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 organized with clear labels (WHEN, PRIORITY TRIGGER, WARNING, Recommended workflow) and is front-loaded with the core purpose. It is somewhat verbose with repeated trigger examples, but each section serves a distinct role and the length is justified by the safety-critical confirmation requirement.

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

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

For a mutation tool with no annotations and no output schema, the description covers the essential context: when to use, prerequisites, required confirmation, and a step-by-step workflow. The only notable gap is the absence of any indication of what the tool returns after posting, but the simple post-comment operation makes that less critical.

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 parameters are already fully documented in the schema. The main description adds no additional parameter-level detail beyond referencing the workflow; the useful 'ready-to-post block' hint actually lives in the schema's commentText description, not in the tool description itself.

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: 'post, add, or save a comment to an ADO Work Item.' It distinguishes itself from the sibling `ado_post_pr_comment` by explicitly targeting Work Items rather than PRs, and from `ado_analyze_workitem` by being the follow-up posting action.

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

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

The description explicitly states WHEN to use the tool ('user explicitly asks to post, add, or save a comment to an ADO Work Item') and provides a recommended workflow that names the prerequisite sibling `ado_analyze_workitem`. It also gives concrete trigger phrases and the critical instruction to ask for user confirmation before invoking.

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: it flags this as a confirmation-gated write action, states the required credentials and permission scope (DEVOPS_ORG_URL + DEVOPS_PAT with Pull Request Threads Read & Write), and insists it run after ado_analyze_pr_impact. It does not disclose idempotency, editability, or deletion behavior of posted comments.

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 well-structured with WHEN, PRIORITY TRIGGER, WARNING, Recommended workflow, and Requirements sections. It is front-loaded with the most important trigger and safety information, and every line contributes operational value.

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

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

For a mutation tool with 6 parameters, no annotations, and no output schema, the description supplies prerequisites, trigger conditions, sequencing, confirmation requirements, and credential expectations. It lacks explicit notes on success/failure behavior or return values, but the core action is straightforward and schema covers the parameters.

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 all parameters and the baseline is 3. The description adds one useful semantic hint—that commentText should use the ready-to-post block from ado_analyze_pr_impact—but otherwise does not materially expand on 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 clearly identifies the action: posting/add/saving a review comment to an ADO Pull Request, with a WHEN trigger and a named prerequisite tool, ado_analyze_pr_impact. However, it does not explicitly differentiate itself from the sibling ado_post_comment, so the distinction is implied rather than stated.

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

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

The description gives explicit WHEN and PRIORITY TRIGGER conditions, mandates user confirmation before calling, and provides a numbered workflow. It does not explicitly say when to use a different tool such as ado_post_comment instead, so alternative routing is incomplete.

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 readOnlyHint=true, and the description is consistent with that. It adds meaningful behavioral detail beyond the annotation by describing the object-conflict detection, branch-chain rules, ordered merge output, and the required DEVOPS_ORG_URL/DEVOPS_PAT scopes.

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 well-structured with a front-loaded purpose, followed by behavioral bullets, output types, triggers, and auth requirements. Though the trigger list is fairly long, it is useful for routing and the overall structure keeps the information scannable.

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

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

There is no output schema, but the description compensates by enumerating the concrete output artifacts: per-PR object table, conflict matrix, dependency graph summary, and ordered merge sequence. It explains the underlying algorithm and required credentials, making the tool sufficiently clear for a five-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?

Schema description coverage is 100%: all five parameters have meaningful descriptions in the schema. The tool description itself does not add parameter-level detail, but the baseline of 3 is appropriate since the schema already carries the burden.

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

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

The description states a specific action, 'Scan multiple Pull Requests and build a cross-PR dependency graph,' and clearly explains the shared object and branch-chain logic. This distinguishes it from siblings like ado_list_prs or ado_review_xpp_pr, which focus on listing or reviewing individual PRs rather than cross-PR conflict and merge-order analysis.

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 explicit trigger phrases for when to invoke this tool, such as 'PR dependencies', 'conflits entre PR', and 'merge order PRs'. It provides clear user-intent context, though it does not explicitly mention when not to use it or name an alternative tool for single-PR 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 declare readOnlyHint=true, and the description does not contradict this. It adds meaningful behavioral context beyond annotations: required env vars (DEVOPS_ORG_URL + DEVOPS_PAT), a max return limit of 50, the exact returned fields, and the 'Use '*' with filters only' quirk.

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 long but well-structured and front-loaded with purpose before triggers, exclusions, shortcuts, output, and requirements. Every segment earns its place, though the trigger keyword list is somewhat extensive.

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 high parameter count, absence of an output schema, and a large sibling set, the description covers purpose, usage triggers, exclusions, query modes, output fields, limits, and prerequisites. Nothing critical for invoking the tool correctly is left out.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantics for the query parameter (shortcuts, WIQL or free-text search, '*' behavior) not fully captured in the schema, but other parameters rely primarily on their schema descriptions.

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

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

The description states a specific action and resource: 'Query Work Items (Bugs, Tasks, FDDs, User Stories, CRs) in Azure DevOps.' It also distinguishes itself from siblings by explicitly saying 'NEVER use this tool for' labels or D365 code and pointing to alternatives like search_labels and search_d365_code.

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

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

It gives an explicit priority trigger keyword list and clear exclusions with alternative tool routing. The description also documents shortcut usage ('bugs', 'my bugs', 'recent', 'sprint') and states when to use other tools, removing 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?

Beyond the readOnlyHint annotation, the description discloses format-specific return behavior (markdown tables for Excel, extracted text for DOCX, base64 data URI for images), size limits (25 MB, 4 MB for images), and unsupported-format fallback behavior. It also names required environment variables. This substantially exceeds the annotation's minimal safety signal.

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 long, but it front-loads the core purpose and then covers usage context, triggers, format behavior, and constraints. Every sentence carries relevant information, though the trigger list is somewhat expansive and could be trimmed. Overall it is appropriately sized for a tool with this much format-specific behavior.

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 and annotations are minimal, the description carries the full burden and delivers: it explains what each input format returns, what happens for unsupported formats, size limits, authentication prerequisites, and the recommended discovery workflow. An agent has enough information to invoke this tool correctly in the supported scenarios.

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 baseline is 3; the description adds meaningful value above that by explaining that fileName must be exact as shown by ado_analyze_workitem and case-insensitive, and by tying supported extensions and sheet behavior to sheetName. This helps the agent use the parameters correctly without contradicting 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 names a specific verb and resource: "Reads the ACTUAL CONTENT of a file attached to a work item," immediately distinguishing it from sibling tools that analyze work items or query them. It also enumerates supported file types and the kind of content returned, so an agent can tell this from ado_analyze_workitem and ado_query_workitems without opening schemas.

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

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

It provides explicit WHEN guidance, concrete trigger phrases, and sequencing instructions: "Call ado_analyze_workitem first (or ado_query_workitems) to discover attachment file names if you don't already know the exact fileName." It also states what will NOT be parsed (PDF, .pptx, .zip) and what happens instead, giving clear boundaries for when this tool is or is not 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 indicate read-only and idempotent behavior, but the description adds substantial behavioral context beyond them: source-branch fetching with fallback to indexed version and notification of fallback, BP findings from a deterministic server-side rule set rather than xppbp.exe, and required credentials/index prerequisites. This transparency goes far beyond 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 well-structured and front-loaded with 'WHEN:', followed by a compact summary of outputs, constraints, and alternatives. It contains no filler, though the trigger-phrase list and some parenthetical rationale add length that may be only marginally necessary.

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 lacking an output schema, the description explains what the response contains, how source is fetched, fallback behavior, why xppbp.exe cannot be used, required environment variables and scopes, and how to use the tool with a sibling. This gives an agent everything needed to invoke it correctly and interpret results.

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

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

Schema description coverage is 100%, so parameters like prId, project, repositoryId, and maxDeepAnalysis are already well documented in the schema. The description does not add additional parameter-level meaning beyond the schema, so 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?

The description clearly identifies the tool's purpose: reviewing PRs that modify X++ code or AOT objects for D365-specific insights, and explicitly states what it returns (structured code review with blast radius, best-practice violations, impact severity). It also differentiates itself from find_error_patterns, helping an agent distinguish this tool from a related one.

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

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

The description opens with 'WHEN: reviewing a PR that modifies X++ code or AOT objects', giving explicit usage context. It also provides routing guidance by saying 'Use find_error_patterns for Microsoft rule text' and suggests combining with ado_post_pr_comment. It lacks explicit exclusion of non-X++ PRs or contrast with other impact-analysis siblings, but the guidance is strong.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that the operation requires a write-scoped DEVOPS_PAT and mandates that the agent show changes and ask for confirmation before invoking, which are meaningful behavioral guardrails for a mutation tool. It does not describe return values or overwrite semantics, so it is not a 5.

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

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

The description is front-loaded with the core action, then gives field scope, trigger phrases, a safety instruction, and permission requirement. Each sentence earns its place, though the trigger list adds some length.

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, combined with the well-documented schema, gives an agent the required parameters, optional project, permission requirements, and a confirmation protocol. It does not explain the return value or behavior on invalid field references, but this is a simple mutation tool and the provided information is sufficient for a correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The main description adds value by explaining that any standard or custom field can be updated via Field Reference Name, reinforcing the schema's examples and making the flexibility explicit.

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: 'Update one or more fields on an existing Azure DevOps Work Item.' It clearly differentiates this from sibling creation, query, and comment tools, and further clarifies scope by naming standard and custom field reference names.

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

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

The description provides concrete trigger phrases in both English and French ('update field', 'mets à jour la description du workitem') to signal when the tool is appropriate, and it states the permission requirement. It does not explicitly contrast with alternatives like ado_create_task, but the context is clear enough for an agent to select this tool.

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 destructiveHint annotation is true, and the description reinforces it by warning the tool replaces the ENTIRE page body and does not merge/append. It also discloses ETag handling and credential/scope requirements, adding meaningful behavioral context beyond the annotation.

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 front-loaded sentences with no filler: purpose, critical usage warning, behavioral guarantee, and auth requirements. Every sentence earns its place.

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

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

For a destructive 4-parameter tool with no output schema, the description covers purpose, usage preconditions, behavior, and authentication requirements. Combined with the fully documented input schema, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces that content replaces existing content and mentions auto-creation of parent pages, but it does not add substantial meaning 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?

States a specific verb and resource: create or overwrite a wiki page with markdown content. It distinguishes itself from sibling tools by explicitly naming ado_wiki_get_page and noting it does not merge/append, making its role unambiguous.

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

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

Gives explicit when-to-use vs alternatives: always call ado_wiki_get_page before editing an existing page instead of replacing it. Also notes parent pages are auto-created and the tool requires specific env vars and PAT scope, leaving little 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?

Beyond the destructiveHint annotation, the description discloses the important side effect that sub-pages under the target page are also deleted. It also surfaces environment variable requirements and the required PAT scope, giving the agent critical behavioral and authorization context.

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

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

The description is compact and front-loaded with the platform constraint and core action. Every sentence adds value: the delete behavior, sub-page consequence, and auth prerequisites are all covered without fluff.

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 delete tool with no output schema, the description covers the essential context: what is deleted, the recursive effect, and required environment variables with scope. An agent has enough information to decide whether to invoke it and what prerequisites must be satisfied.

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 path, project, and wikiIdentifier clearly. The description adds no parameter-specific meaning beyond noting environment requirements, which is acceptable at the baseline for fully covered schemas.

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: 'Delete a wiki page', and clearly distinguishes behavior by noting sub-pages are also deleted. This separates it from sibling wiki tools like ado_wiki_get_page and ado_wiki_create_or_update_page.

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 'AZURE DEVOPS ONLY' prefix gives clear platform context, and the delete verb makes the intended use obvious. However, it does not explicitly name alternatives or state when to prefer ado_wiki_create_or_update_page over this tool, so it stops short of a 5.

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

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

The readOnlyHint annotation already signals safety; the description adds useful behavioral context by noting the env var requirements, the path syntax constraint, and the fact that immediate sub-page paths are also returned. It does not describe error behavior or output format, but for a read operation this is acceptable.

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 that front-loads the critical Azure DevOps constraint, states the operation, gives concrete path examples, and mentions required env vars. No filler or 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?

Given the low complexity, full schema coverage, and readOnlyHint annotation, the description covers the essential operational details: Azure DevOps scope, path format, env var prerequisites, and the inclusion of sub-page paths. It could mention the exact return structure, but this is not a critical gap for a simple read tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description reinforces path syntax and env var fallbacks but does not add substantial meaning beyond what the schema provides.

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 explicitly states the verb 'Read' and the resource 'wiki page', and further specifies that it returns the page's content plus immediate sub-page paths. This clearly differentiates it from sibling tools like ado_wiki_create_or_update_page, ado_wiki_delete_page, and ado_wiki_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?

The description provides strong usage context: it is confined to Azure DevOps, requires specific env vars, and uses wiki path syntax. It does not explicitly state when to prefer this over sibling tools, but the read-only purpose and syntax guidance make the intended 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?

The readOnlyHint annotation already signals a safe read operation, and the description adds useful behavioral context by emphasizing the Azure DevOps-only scope and the required DEVOPS_ORG_URL and DEVOPS_PAT environment variables. This helps the agent prepare prerequisites before invoking 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 compact and front-loaded, with every sentence delivering actionable information: scope, usage timing, and prerequisites. There is no filler, repetition, or unnecessary detail.

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 read-only list operation with one optional parameter, the description covers the purpose, when to invoke it, and operational prerequisites. Nothing essential is missing for an agent to select and call this tool correctly.

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

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

The input schema already fully documents the single optional 'project' parameter, including its fallback to the DEVOPS_PROJECT env var. The description does not add additional semantic details about the parameter, so the schema carries the burden, which is acceptable at 100% 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?

The description clearly states a specific action — 'List all wikis in a project' — and identifies the exact resource scope, including both the project wiki and published code-as-wiki repos. The 'AZURE DEVOPS ONLY' prefix and the list-oriented wording distinguish it from the sibling wiki page tools without ambiguity.

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

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

The description explicitly tells an agent when to use this tool: 'Use this FIRST when the user doesn't know the wiki's exact name/id, or to confirm which wiki to target before reading/writing a page.' This gives clear usage context, though it does not explicitly name alternative sibling tools or describe when not to use it beyond the implicit 'first step' framing.

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 annotations declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral context beyond those: it cross-references every coC target, event handler, extension, and hard-coded reference; it lists specific categories of detected breakage; and it states that it returns a prioritized risk report with fix recommendations. The 'Requires D365_CUSTOM_MODEL_PATH' precondition is also useful context. No contradiction with 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 organized front-to-back with WHEN, trigger examples, analysis scope, detection categories, output, and prerequisite. It is long but every clause earns its place; the density is high and the structure makes scanning easy.

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 analysis tool with no input schema and no output schema, the description is remarkably complete: it covers when to use it, what it inspects, what it detects, what it returns, and what it requires. Nothing essential for an agent to decide whether to invoke it 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?

The input schema is empty (0 parameters), so the baseline is 4. The description adds the meaningful prerequisite 'Requires D365_CUSTOM_MODEL_PATH,' which supplements the empty schema, though it does not clarify how the path is supplied (param, environment, or context). Still, with no parameters to document, this dimension is well handled.

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 specific verb and resource: 'Analyze upgrade risk for your custom D365 F&O model.' It also distinguishes the tool by tying it to upgrade/update scenarios and by enumerating the types of custom-code constructs it checks (CoC targets, event handlers, extensions, hard-coded references). The 'WHEN' framing plus trigger examples make the 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 explicitly says when to use the tool: 'upgrading D365 F&O to a new version or applying a Microsoft update,' and provides concrete trigger phrases in English and French. It lacks explicit exclusions or named sibling alternatives, so it stops short of full when-not/however guidance, but the usage context is very 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?

With no annotations provided, the description carries the full behavioral burden. It clearly discloses the state-changing behavior (removing a cached connection), the session scope, and the tool that created the connection. It does not mention edge cases like calling it with no active connection, but this is a minor gap for such a simple operation.

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, well-structured sentence with no filler. It front-loads the core action and immediately names the prerequisite tool, making it easy for an agent to parse quickly.

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, no-output-schema tool, the description fully explains what the tool does, what resource it affects, and the session scope. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add. Per the baseline for zero-parameter tools, a score of 4 is appropriate.

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

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

The description uses a specific verb ('Removes') and a clear resource ('Application Insights connection cached for the current session'), while explicitly referencing the complementary tool that creates the connection. This cleanly distinguishes it from sibling tools like appinsights_set_connection and appinsights_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 conveys clear usage context: it is used to remove a session-scoped connection that was established by appinsights_set_connection. It does not explicitly state when not to use it or list alternatives, but for a zero-parameter lifecycle tool the context is sufficient.

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 behavioral disclosure burden and does it reasonably well. It explains that the tool runs canned KQL queries, assembles a combined report, conditionally renders sections based on data availability, and requires a configured connection. It does not address potential runtime cost or error behavior, but for a diagnostic read tool the disclosed behavior is sufficient.

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 longer than average but well structured: it front-loads the WHEN scenario, then lists the report contents in an easy-to-scan numbered format, and ends with trigger phrases. The trigger list is somewhat redundant with the opening WHEN, but it helps with invocation matching and does not feel like 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?

For a tool with no output schema, the description compensates by detailing the three sections the report will contain and their conditional rendering. It also states the required connection prerequisite and the parameters are fully documented in the schema. The only small gap is the lack of explicit behavior when no connection has been configured, but the prerequisite is already stated.

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 covers all three parameters with descriptions, defaults, and valid ranges, so the description does not need to add much. The report description slightly reinforces the role of minDurationMs and top, but overall the parameters are already fully documented 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 opens with a clear WHEN statement and defines the tool as diagnosing why a D365 F&O environment is slow using existing Application Insights telemetry, with no trace upload. It enumerates exactly what the combined report contains, making its purpose concrete and distinguishable from generic App Insights query tools.

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

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

The description explicitly states when to use it: when the user wants to understand slowness from App Insights telemetry. It also names the prerequisite of configuring the connection via appinsights_set_connection or server env vars. However, it does not explicitly contrast itself with sibling tools like appinsights_query or detect_performance_issues, leaving alternatives 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 clearly discloses that the operation is read-only, notes the prerequisite connection setup, and names the standard App Insights tables/schema. It does not describe output formatting or error behavior, but the safety profile and operational context are well covered for a query tool.

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

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

The description is front-loaded with purpose and read-only behavior, followed by prerequisites, alternatives, and trigger examples. It is efficient overall, though the trigger phrase list is somewhat redundant for an agent that can infer intent from the main description; still, it does not introduce meaningful bloat.

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 tool's complexity, the description covers purpose, read-only guarantee, required setup, targeted schema, parameter behavior, and the alternative sibling. The main gap is that no output shape or error behavior is described, but since there is no output schema and the tool returns arbitrary KQL query results, this is a minor omission.

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

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

The input schema already documents all three parameters with 100% coverage, including defaults and range constraints, so the description need not repeat them. The main description adds domain context about the standard App Insights schema but does not add significant parameter-level semantics beyond what the schema provides, matching 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?

The description states a specific verb and resource: run a raw KQL query against the D365FO environment's Application Insights / Log Analytics workspace. It also names the sibling alternative appinsights_diagnose_slowness and distinguishes this tool as the custom/specific query path, so an agent can tell them apart without opening schemas.

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

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

It explicitly states the prerequisite that a connection must be configured via appinsights_set_connection or server env vars, and it gives a clear when-to-use versus when-not-to-use rule: prefer appinsights_diagnose_slowness for ready-made slowness reports, use this tool for more specific/custom queries. Trigger phrases are also provided, making selection unambiguous.

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

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

No annotations are present, so the description carries the full burden. It discloses memory encryption (AES-256-GCM), no disk writes/echoing, session lifetime, automatic consumption by later tools, and the locked-server disable condition. It explicitly states read-only authorization is sufficient and no write access is used.

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 longer than average, but the length is earned: it front-loads the core purpose and security guarantees, then organizes credential acquisition in a clearly headed section. No redundant sentences; the locked-server caveat is a necessary edge case.

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 state-setting tool with no output schema and no annotations, this description covers prerequisites, side effects, lifetime, security, and disabled behavior. It does not detail the success response, but for a registration call that is low-risk and the remaining guidance is sufficient for an agent to invoke it correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds substantial meaning: workspaceId is a GUID not the App Insights app id, with a D365FO UI path; tenant/clientId/clientSecret require an Entra ID app registration with Log Analytics Reader/Monitoring Reader role and no write access. This goes well beyond the schema property descriptions.

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

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

States a specific action ('Securely register ... connection for the CURRENT session'), names the resource (D365 F&O environment Application Insights/Log Analytics connection), and differentiates from siblings by explaining that appinsights_query and appinsights_diagnose_slowness will consume it and appinsights_clear_connection will clear it.

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

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

Provides explicit usage context: session-scoped, automatically used by appinsights_query and appinsights_diagnose_slowness, cleared by appinsights_clear_connection or expiry. Also gives a clear exclusion: in locked server deployment with APPINSIGHTS_LOCK_SERVER_CONFIG=true the tool is disabled and server credentials are used instead. It also tells the user how to obtain each credential, which is a form of usage guidance.

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

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

Annotations only declare readOnlyHint=true, but the description adds important behavioral context: queries run in parallel, each line becomes one search, results are fully loaded with all chunks, and no follow-up detail fetch is needed. This goes well beyond the annotation and prevents redundant agent actions.

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 WHEN/INSTEAD message, followed by capacity limits, behavioral equivalence, and a clear anti-pattern. The trigger list is somewhat long but earns its place by helping the agent recognize when to choose this 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?

For a multi-query search tool with no output schema, the description sufficiently covers when to use it, how queries map to searches, limits, result equivalence, and post-call behavior. An agent has everything needed to invoke it correctly and avoid unnecessary follow-up calls.

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 already covers all parameters with descriptions, so the baseline is 3. The description adds meaning by clarifying that each newline-separated query becomes a parallel search, enforcing the max 6 behavior, and explaining that topObjects controls full-chunk loading per query.

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

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

States a specific purpose: run multiple D365 object/concept searches in parallel. It explicitly says results are equivalent to search_d365_code but returned together, distinguishing it from the closest sibling without ambiguity.

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

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

Provides explicit when-to-use guidance, tells the agent to use it INSTEAD of multiple sequential search_d365_code calls, sets a maximum of 6 queries per call, and even lists concrete trigger phrases. It also warns not to follow up with get_object_details because objects are fully loaded.

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 idempotentHint=true, covering the safety profile. The description adds meaning about what is compared (fields, methods, signatures) but does not disclose the return shape, pagination, or behavior on missing objects. Given the annotations, this is a reasonable but not rich level of behavioral context.

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

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

Two sentences with no filler. The core action and scope are front-loaded, and the use cases add useful context 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?

For a simple two-parameter read-only tool, the description clearly communicates purpose, scope, and typical use cases. The lack of an output schema and explicit return-value description is a minor gap, but the overall context is adequate for effective tool selection and invocation.

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

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

The input schema provides 100% coverage of both parameters with descriptive examples ('SalesTable', 'PurchTable'). The description adds no parameter-specific information, so the baseline score of 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?

The description states a specific verb ('Compare'), a concrete resource ('two D365 F&O objects'), and the exact dimensions being compared ('fields, methods, signatures'). This clearly distinguishes it from sibling tools like diff_model_versions, which compares versions, and get_object_details, which retrieves object details.

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 gives two clear use cases: investigating differences between standard and customisation, or between two similar tables. It does not name alternative tools or exclusions, but the context is sufficient for an agent to decide when to invoke 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?

Beyond the readOnlyHint annotation, the description explicitly states 'fully read-only on the server: it never writes to the filesystem, never mutates external state, and is safe to expose from the cloud MCP.' This goes beyond the annotation by explaining side effects, caller responsibility for writing to disk, and the returned artifact. No contradiction exists between the annotations and prose.

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 long, but this is justified by the polymorphic nature of the tool with 20+ supported aotTypes. It front-loads the core result and read-only guarantee, then organizes options in clear type-specific sections. The structure lets an agent find exactly the relevant option block without unneeded 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?

Given the tool's complexity, the description covers what an agent needs to invoke it correctly: supported aotTypes, per-type option syntax, defaults, constraints, and return shape ('XML + the correct file path'). The output schema is absent, but the description supplies the essential output contract. No critical invocation requirement appears 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 description adds substantial semantics: exhaustive aotType-specific options, CSV syntax, defaults, enum values, constraints (e.g., extension values starting at 10), and examples. The description explains the meaning of option keys far beyond the schema's generic 'Key-value options dict'.

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: 'Generate a complete, ready-to-deploy D365 F&O AOT XML scaffold for any object type.' It clearly states what the tool does and distinguishes it from the broad sibling set through the unique 'AOT XML scaffold' scope. It also clarifies the boundary with 'the calling client is responsible for writing the result to disk.'

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 intended usage is clear: when an agent needs a ready-to-deploy D365 F&O AOT scaffold for a supported aotType. The description does not explicitly name alternatives or formulate when-not-to-use conditions, but the highly specific purpose makes the usage context obvious. A fully explicit routing to sibling tools would be needed for a 5.

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

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

With no annotations, the description carries the behavioral burden and adequately discloses that the operation removes cached connection state and that the effect is session-scoped. It also implies mutative behavior without hiding side effects, though it could note that a new connection must be set afterward.

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

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

A single sentence that front-loads the action and resource, then adds the essential scoping detail. Every word contributes meaning 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?

For a zero-parameter, no-output-schema clearing operation, the description is complete. It identifies what is removed, the scope of removal, and the origin of the cached connection, which is all needed to invoke it correctly.

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

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

The tool has zero parameters, so the description has no parameter burden. Baseline 4 is appropriate because the description correctly focuses on what the action does rather than on nonexistent 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?

States a specific verb ('Removes'), the precise resource ('D365 F&O connection cached for the current session'), and ties it explicitly to its counterpart d365fo_set_connection. This clearly distinguishes it from generic clear/set tools like appinsights_clear_connection.

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?

Makes the usage context clear by specifying that it clears the connection previously cached by d365fo_set_connection for the current session. It does not provide explicit when-to-use vs alternatives, but the counterpart reference and session scoping give enough guidance.

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

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

With no annotations, the description carries the full burden and does so thoroughly: in-memory AES-256-GCM encryption, no disk persistence, no echoing, session-scoped caching, expiry behavior, and the disabled locked-server path. This is far beyond a minimal mutation warning and gives the agent accurate behavioral expectations.

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

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

Two tight paragraphs with front-loaded purpose, followed by security behavior and the deployment exception. Every sentence adds information; no filler, no restating of schema defaults.

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?

Invocation-critical context is complete: what the tool does, how long the connection lasts, what consumes it, and when it is unavailable. The only minor gap is the lack of any description of the response/error behavior, but since no output schema exists and this is a simple setter, the missing piece is not severely damaging.

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 every parameter. The description adds useful grouping context ('URL + Entra app-registration credentials') and security emphasis for clientSecret, but it does not need to detail each parameter further. Baseline 3 is appropriate.

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

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

The description states a specific action ('Securely register the D365 F&O connection') with a clear resource (URL + Entra app-registration credentials) and scope (CURRENT session). It also distinguishes itself from d365fo_clear_connection and implicitly from appinsights_set_connection by naming the D365 F&O context and the odata_*/dmf_* consumers.

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 when to use it ('Use this instead of resending the secret on every call'), defines the automatic consumption by odata_* and dmf_* tools, and states a clear when-not case with D365FO_LOCK_SERVER_CONFIG=true. This gives an agent concrete conditions for 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 readOnlyHint and idempotentHint annotations already cover the safety profile; the description adds the analysis scope, the compact issue-table output with line and fix, and an environment prerequisite for auto-fixing. The auto-fixing note is slightly ambiguous, but because the tool is framed as profiling and returning results, it does not contradict the read-only annotation.

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 each carry load: the analysis scope, the output shape, the routing rule, and the environment dependency. The most important verb-resource information is front-loaded, 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 analysis tool with a 100%-covered schema, the description supplies everything needed to call it appropriately: what it checks, what it returns, when to prefer it, and a critical operand for auto-fixing. There is no output schema, but the return format is described well enough.

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 already documents both parameters with 100% coverage, including the optional methodName default and an objectName example. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 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?

The description names a specific verb ('Profile') and a specific resource ('X++ object'), and enumerates the exact issue classes it detects: N+1 queries, queries in loops, missing field lists, row-by-row inserts/updates, and missing firstOnly. It also differentiates itself from validate_best_practices by positioning itself as performance-specific, so an agent can select it confidently.

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

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

It states an explicit trigger ('Only call when performance is explicitly the concern') and an explicit exclusion ('for general quality use validate_best_practices'), naming the alternative tool. This is exactly the when/when-not guidance that lets an agent 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 the description is consistent with that. It adds behavioral context beyond the annotation: the tool is stateful in that save_baseline persists a baseline state, and the output is a changelog of three change types. No contradiction with the read-only hint since saving a local cache file does not mutate the observed system.

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 with no filler: the first front-loads purpose and output type, the second conveys the required call sequence. 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 tool with three distinct actions and no output schema, the description covers the primary workflow and main use case, while the schema fully documents the remaining 'compare_caches' action and filterModel parameter. Minor gaps remain (no guidance on when compare_caches is preferable, no changelog format details), but the rich schema compensates.

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 each parameter description already explains its per-action meaning (e.g., path1 as baseline cache, output path, or first cache). The description adds only sequencing value (save baseline before comparing), not new parameter semantics, so the baseline of 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?

The description states a specific verb ('Compare'), a precise resource ('two D365 F&O KB snapshots'), and a concrete outcome ('changelog with added/removed/modified objects'). This is specific enough to distinguish from the closest sibling 'compare_objects', which operates on objects rather than KB snapshots.

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

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

Gives a clear, actionable workflow: 'Use action save_baseline once, then compare between two snapshots.' This tells the agent the required call sequence, though it does not explicitly name alternatives or state when NOT to use this tool (e.g., versus compare_objects or compare_caches).

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 only provide `readOnlyHint: false`, so the description carries most of the burden. It usefully discloses that each action forwards to the exact same implementation and validation as the corresponding dedicated tool. However, it does not directly describe side effects like overwriting projects, return payloads, error behavior, or polling semantics beyond naming `pollTimeoutSeconds`.

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 each action is described in a compact, scannable line. The length is justified by the dispatcher design with 5 operations and 20 parameters, 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?

Action selection and parameter mapping are well covered, which is the core invocation need. However, with no output schema, the description should more directly state what each action returns, such as execution IDs or status payloads; it largely relies on the assertion that behavior is identical to the dedicated tools.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by grouping the 20 flat parameters by action and marking optional ones with `?`. It also makes the `filePath OR csvContent` alternative explicit, which is not obvious from the schema alone.

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 immediately states it is a consolidated entry point for all 5 DMF operations, maps each `action` value to a named dedicated tool, and lists the exact parameter sets per action. This is specific about verb, resource, and scope, and cleanly distinguishes it from the five `dmf_*` sibling tools.

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

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

It says the tool is the 'one entry point' for all five DMF operations and notes that dedicated tools remain available unchanged, which tells an agent how this tool relates to its alternatives. It does not explicitly state when to prefer the consolidated tool over a dedicated one, but the claim of identical behavior makes the choice low-risk.

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 establish idempotency and non-destructiveness, and the description goes well beyond them: it discloses the internal kernel mechanics (QueryRun.ack, stripped container envelope, PATCH onto QueryData), wildcard pass-through, the parent/child filtering gotcha, and an environment prerequisite. This gives an agent accurate expectations for side-effects and dependencies.

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 captures the primary purpose, and every subsequent sentence contributes a non-obvious constraint, caveat, or prerequisite. Despite its technical depth, there is no filler or 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?

The description covers the action, target, constraints, environment requirement, and the most important limitation (parent filtering does not cascade to child rows). For a mutation tool with no output schema, an agent has enough to invoke it correctly and anticipate its effect.

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 already documents every parameter with examples, so the baseline is 3. The description adds semantic constraints beyond the schema: one field per call, one value per field, call once per entity row, and that the filter applies to an existing DMF project. This enriches rather than merely repeats the structured definitions.

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

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

The first sentence states an explicit verb and resource: 'Apply a single-field value filter to ONE entity row of an existing DMF project'. It also specifies the scope ('single field = single value per call') and the effect on exports, which clearly differentiates this tool from DMF export or query-generation 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 description specifies clear conditions: it works for ANY entity/field, requires an existing DMF project, must be called once per entity row, and requires the custom 'GenerateQueryData' action. It also warns about child rows not being auto-filtered. It does not explicitly name alternative tools or say when not to use it, so it stops short of a 5.

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

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

Beyond the idempotentHint and destructiveHint annotations, the description discloses concrete implementation behavior: it POSTs to DataManagementDefinitionGroups and DataManagementDefinitionGroupDetails, sets AutoGenerateMapping=Yes, reuses existing projects, and skips already-present entities. 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?

Four dense sentences, each earning its place: purpose, mechanism, idempotency, and next-step guidance. The key purpose is front-loaded and there is no filler or redundant restatement of 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?

The tool has only four simple parameters and no output schema, and the description fully explains the create/extend behavior, idempotency, and next step for EXPORT. The only notable gap is that the import execution path (via dmf_import_file) is not explicitly mentioned, but the core call is 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 the baseline is 3. The description adds value by requiring sourceName to be an EXISTING DMF source data format and giving a concrete comma-delimited example. It also reinforces that entities are comma-separated, going slightly 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 uses a specific verb-resource pair ('Create (or extend) a DMF data project') and clearly scopes the tool to EXPORT or IMPORT. It distinguishes this configuration tool from execution siblings like dmf_export_package and dmf_import_file by stating that it builds the project through OData entities rather than running it.

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 explains the OData/no-X++ approach, states idempotency behavior, and explicitly routes the EXPORT project to dmf_export_package for execution. It does not explicitly mention when not to use it or name the import execution counterpart (dmf_import_file), so it stops short of a 5.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that the tool triggers an export, waits for completion, and then returns a download URL, which communicates the asynchronous/polling nature. It does not discuss side effects like staging reuse or failure behavior, but the main operational behavior is clear.

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 primary action, then adds a prerequisite note and a clear alternative. Every sentence earns its place, and there is no redundant repetition of schema information.

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

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

The description gives the core output (download URL), the prerequisite project setup, and the routing alternative, which is strong for a 5-parameter tool with no output schema. It could additionally note failure/timeout outcomes, but the parameter schema already covers pollTimeoutSeconds, so the overall picture is sufficiently 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 all five parameters are already documented with meaningful descriptions. The tool description adds high-level context about definitionGroupId being an existing DMF project, but does not need to repeat parameter details because the schema already handles them.

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 triggers a bulk export via the Data Management package REST API and returns a download URL when complete. It distinguishes itself from related tools by emphasizing the project-based export path and explicitly naming odata_export_entity as the alternative for ad-hoc exports.

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 explicit when-to-use guidance: use this when a DMF export project already exists. It also says to create the project with dmf_create_data_project if needed, and to use odata_export_entity for ad-hoc exports without a project. This leaves little ambiguity about tool selection.

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

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

With no annotations, the description carries the behavioral disclosure burden. It clearly conveys a non-mutating polling operation, enumerates the possible status values, and discloses extra return behavior for completed exports (download URL). It does not explicitly state 'read-only' or describe failure handling, but 'Poll the status' sufficiently implies the safety profile.

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 two concise sentences with no filler. The core action and the key identifier are front-loaded, followed by the useful status examples and the download URL detail. Every sentence earns its place.

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

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

For a simple single-parameter polling tool with no output schema, the description provides enough context: what to provide, what statuses to expect, and a special return case. It could arguably mention that the executionId must come from a prior DMF operation, but the schema already supplies that dependency, so the overall definition is complete enough.

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 only parameter, executionId, is already described as the ID returned by dmf_import_file or dmf_export_package. The description's mention of 'executionId' adds no new semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Poll') and resource ('a DMF import/export execution'), and identifies the required identifier ('executionId'). It also includes concrete status examples and a distinctive note about the download URL, making it easy to distinguish from sibling DMF tools like dmf_import_file and dmf_export_package.

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 the outcome of a prior import/export operation, especially with the schema noting that executionId comes from dmf_import_file or dmf_export_package. It does not explicitly name alternatives or state 'use this instead of X', but the polling purpose is unambiguous enough for correct tool 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?

Annotations already carry destructiveHint and openWorldHint, so the bar is lower. The description adds valuable behavioral context: builds package in memory, uploads to Azure blob, calls ImportFromPackage, auto-creates the data project, polls to completion, and returns an error-keys file URL on failures. It does not contradict the annotations and supplies meaningful side-effect detail beyond what annotations 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?

The description is four sentences, front-loads the core purpose, and each sentence earns its place by describing mechanism, execution behavior, or invocation guidance. There is no fluff or repetition beyond what is useful for a complex, side-effectful 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?

Given the tool's complexity, the description covers the key invocation inputs, execution flow, polling, and failure reporting well. The main gaps are the lack of explicit treatment of the execute=false staging-only path and the absence of mention of connection prerequisites; however, annotations and schema mitigate most of these omissions, and the description is otherwise quite 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 coverage is 100%, so the baseline is 3. The description adds genuine value by emphasizing the filePath/csvContent exclusivity and by instructing the agent to resolve entity names via find_entity_for_table rather than inventing them. This reduces the risk of incorrect entityName values beyond what the schema alone provides.

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: 'Bulk-import a CSV file into a D365 F&O entity through the Data Management package REST API.' This clearly distinguishes the tool from siblings like dmf_export_package, dmf_transform_excel, and generate_data_entity. The auto-create and polling behavior further sharpen what this specific tool does.

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 a clear batch-CSV-DMF use case and gives practical guidance such as 'Provide either filePath or csvContent' and 'Resolve the entity name from the KB... do not invent it.' However, it does not explicitly state when to prefer this tool over alternatives like odata_upsert_rows or dmf_create_data_project, nor does it name sibling exclusions.

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

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

With no annotations, the description carries the disclosure burden and does so well: it notes no FO credentials are needed, base64 upload is only for small files, autoGeneratedFields are removed so FO regenerates them, and output is CSV or JSON with downstream consumers. It stops short of detailing side effects such as outputPath file writes or error behavior, but the core behavior is transparent.

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 text is dense but organized: main action, credential caveat, source alternatives, mapping spec summary, outputs, and diagnostic mode. Every sentence carries distinct information, and there is no filler or tautology.

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 8-parameter tool with no annotations and no output schema, the description covers all essential usage aspects: input source alternatives, mapping JSON structure, output formats and downstream routing, plus a diagnostic mode. An agent has enough to select and invoke it correctly.

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

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

Schema description coverage is 100%, but the description adds substantial meaning beyond it: the mappingJson supported keys and shapes, the sourceUrl variants, file size caveat, format-to-downstream-tool mapping, and listSheetsOnly diagnostic purpose are all explained. This deeply complements the parameter 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 opens with a specific verb-resource pair: 'Transform a multi-sheet Excel (.xlsx) into DMF-ready rows using a data-driven JSON mapping.' It also states it is the offline equivalent of FO_TransformExcelForDMF and explicitly routes output to dmf_import_file or odata_upsert_rows, which distinguishes it from sibling tools.

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

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

Clear context is given: use it to prepare Excel data offline before importing via dmf_import_file or upserting via odata_upsert_rows, and use listSheetsOnly for inspection. However, it never explicitly states when not to use it (e.g., when data is already DMF-ready) or compares it to a direct alternative.

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 indicate readOnlyHint=true. The description adds meaningful behavioral context beyond that: output is plain business language, no X++ or workflow engine jargon, and it covers approval/rejection outcomes. This helps set expectations for the response style.

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 well-structured with WHEN, NOT, and trigger sections, and the key scoping information is front-loaded. The trigger list is slightly redundant with the opening WHEN clause, but it adds concrete value for intent matching.

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, single-parameter tool with no output schema, the description provides everything an agent needs: when to use it, what it explains, the output language style, and the exclusion boundary. No critical context 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 parameter description already provides examples like 'SalesTable' and 'ALMDemandeAchatWorkflow'. The tool description does not add new parameter-level meaning, but with full schema coverage the baseline of 3 is appropriate.

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-resource pair: explains a D365 approval workflow, covering who approves, states, and outcomes. It clearly distinguishes itself from get_object_details by explicitly excluding technical workflow class details.

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

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

Provides explicit WHEN conditions with concrete user-question examples, and an explicit NOT condition with the alternative tool to use (get_object_details). Trigger phrases, including multilingual examples, leave no ambiguity about when to invoke this tool.

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 readOnlyHint annotation, the description reveals useful behavioral traits: parallel fan-out, RRF-based result merging, peer configuration via D365_FEDERATION_PEERS, and the local server always being the primary source. These details help the agent anticipate how the tool behaves and how it is configured.

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 tight sentences, each earning its place: the core action, the target use case, the peer configuration mechanism, and the local-server inclusion. It is front-loaded with the most important information and contains 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?

The description together with the fully-documented schema gives an agent enough to invoke the tool correctly: query is required, topK defaults to 5, peerApiKeys are optional, and peers come from an env var. It doesn't describe the exact output shape or RRF details, but those are not strictly required for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (query, topK, peerApiKeys) including defaults and ordering semantics. The description adds little parameter-level detail beyond what the schema provides, so the baseline 3 is appropriate.

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: 'Fan-out search across multiple ALM XPP MCP server instances in parallel and merge results using Reciprocal Rank Fusion (RRF).' It clearly distinguishes this federated, multi-server tool from the many single-server search tools in the sibling list, such as search_d365_code or batch_search.

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 states a clear use case: 'Useful when D365 code is split across multiple organisations or knowledge bases (e.g. one per client, one standard KB).' This gives the agent good context for when to invoke it, though it does not explicitly name alternatives or state when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral detail beyond that: it calls out the dependency on xref_index.json.gz, explains how that index is generated, and discloses the vector-search fallback behavior when the index is unavailable.

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 first sentence states the core purpose and output categories, the second gives the prerequisite, and the third describes fallback behavior. Every sentence earns its place and there is no redundant or filler content.

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

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

Given no output schema, the description still gives enough shape of what to expect by listing the major output categories and mentioning the fallback mechanism. It covers prerequisites and operational behavior, though it does not describe the exact return format or how depth/maxResults affect results beyond what the schema provides. This is a minor gap for a complex cross-reference tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters clearly. The description adds no parameter-specific semantics beyond what the schema provides; it reinforces the category list but does not explain defaults, formats, or constraints 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 clear verb and resource: it produces a full cross-reference profile for a class or method, enumerating callers, callees, inheritance, interfaces, overrides, and attributes. It distinguishes itself from the narrower tool name 'find_callers' by explaining the broader scope, though it does not explicitly name a sibling tool for comparison.

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

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

The description implies usage for cross-reference exploration and provides important context: it requires xref_index.json.gz and falls back to vector-search when the index is not loaded. However, it does not explicitly state when to choose this tool over similar siblings like find_references, find_change_impact, or find_related_objects, so the routing guidance is implied rather than explicit.

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 indicate readOnly and idempotent behavior. The description adds meaningful operational context: the XRef index prerequisite, BFS traversal up to 3 hops, and the categories of impact included. This goes beyond the annotations without contradicting 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?

The description is longer than average, but it is well-structured with a WHEN clause, output summary, requirement note, trigger phrases, examples, and workflow suggestion. The trigger phrase list is somewhat repetitive but serves a real routing purpose. Overall, each section 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 tool with no output schema, the description conveys the return format well enough by listing the blast-radius components and severity levels. It also covers prerequisites, parameter usage, and a sensible combination with other tools. An agent has enough information to decide when and how to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the semantic difference between table/class-level objectName values and method-level values like 'SalesLine.insert', and by linking maxDepth to the BFS behavior. This is helpful but not extensive, given the schema already documents both 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 states this tool computes change impact for X++ objects/methods and enumerates the concrete outputs: direct callers, transitive dependents, custom model extensions, interface propagation, and severity classification. This distinguishes it from generic search or reference tools like find_callers or find_references, even though those siblings are not 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 WHEN clause is explicit ('about to modify an X++ object or method and need to understand what could break'), and the trigger phrases plus objectName examples provide strong contextual guidance. It does not explicitly say when not to use this tool versus closely related siblings, so it stops short of a 5.

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

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

Annotations declare readOnlyHint and idempotentHint; the description is consistent with these and adds the key behavioral trait annotations cannot express: invoking with generateIfMissing=true writes a new AxDataEntityView XML template, a side effect normally hidden by the readOnly profile. It also discloses the scan scope ('all indexed AxDataEntityView objects') and the exact returned fields. No contradiction, though it does not cover auth needs or error/reversibility of the generated template.

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

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

Well-structured and front-loaded with the WHEN clause, followed by triggers, behavior, returns, and the conditional generation note. However, it repeats the generateIfMissing behavior twice, includes filler ('Essential for integration development'), and the trigger phrase list is longer than needed.

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's explicit list of return values (entity name, public entity name, IsPublic status, key fields, all data sources) is valuable and largely compensates. Combined with trigger phrases, scan scope, and the generation side effect, it is complete for the primary use case — the only notable gap is routing guidance to sibling tools.

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

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

Schema description coverage is 100% with substantive param documentation (defaults, max value, and the generateIfMissing behavior). The description mostly restates what the schema already says about generateIfMissing and the SalesTable example rather than adding new meaning, so the baseline 3 is appropriate.

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: 'Find D365 F&O data entities that expose a given table for OData/DMF integrations.' It further distinguishes itself from siblings by naming its exact return payload (public entity name for OData URL, IsPublic status, key fields, data sources) and its conditional generation behavior, which separates it from get_data_entity_info and generate_data_entity 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?

Leads with an explicit WHEN clause targeting OData integration developers who need an entity name for a given table, and provides both trigger phrases and a concrete example question ('Which entity exposes SalesTable for OData?'). It also states the condition for the generation path (no public entity found and generateIfMissing=true). However, it never names sibling alternatives or says when not to use this tool versus get_data_entity_info or generate_data_entity, 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 mark the tool as read-only and idempotent, and the description is fully consistent with that. It adds meaningful behavioral detail beyond annotations: the tool matches against a built-in error database, resolves D365 label IDs, searches the indexed codebase, and returns root causes, step-by-step resolution, label matches, and source locations. It also clarifies the distinct role of the best-practice moniker path.

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 long and dense, but nearly every section earns its place: triggers, label-resolution routing, best-practice rule distinction, and audience behavior are all actionable. The structure front-loads WHEN guidance and then proceeds through resolution behavior and edge cases. It is slightly verbose due to the extensive trigger lists, but this density is functionally useful for triggering and disambiguation.

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 two simple parameters, no output schema, and read-only annotations, the description covers what an agent needs: what input to supply, how to handle label IDs, how audienceType changes behavior, what the tool returns, and how it relates to sibling tools. Missing details such as exact output formatting are not necessary for correct invocation here.

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 both parameters. The description adds value by giving concrete example values for errorOrSymptom ('update conflict', 'number sequence not set up') and by explaining audienceType='business' as plain-language explanation for end users rather than developer root-cause analysis. This enriches the schema without being redundant.

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: 'Find known D365 F&O error patterns matching an error message or symptoms description.' It also names the matching mechanisms (built-in database, label resolution, codebase search) and explicitly differentiates from related tools like search_labels and run_best_practices_check_scoped. A developer trigger list further disambiguates when this tool, rather than a generic search tool, is appropriate.

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 explicit WHEN guidance for both developer and business audiences, including concrete trigger phrases. It also provides direct routing: if the error text contains a label ID, call search_labels first; for best-practice rule text, use this tool with the moniker, but use run_best_practices_check_scoped to decide whether an object violates it. This leaves little ambiguity about alternatives.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds meaningful behavioral detail: it searches the knowledge base for SubscribesTo attribute patterns rather than doing live code execution. It also explains eventName narrowing, though it does not disclose limitations such as potential misses for handlers not using the documented pattern.

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 and front-loaded with the core purpose, then details the search mechanism and usage triggers. The WHEN list is somewhat long but earns its place by providing actionable routing cues.

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 readOnly annotation, clear parameter schema, and explicit search-pattern explanation, the description is sufficient for selecting and invoking the tool. It does not describe the return format, but the absence of an output schema is partially mitigated by the clear 'find all event handlers' outcome implied in the first sentence.

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 parameters. The description adds a little value by explicitly explaining that eventName narrows results and giving an example, but it does not add meaning for handlerType or objectName beyond the schema descriptions.

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

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

The description clearly states it finds event handlers subscribing to events on a D365 table or class, and specifies the searched attribute patterns. It is distinguishable from generic search tools, though it does not explicitly name or contrast any sibling 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 provides explicit WHEN trigger phrases including natural-language intents and French equivalents, giving clear context for when the tool is appropriate. It does not explicitly state when not to use it or name alternatives, but the usage cues are 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 the tool read-only and idempotent. The description adds meaningful behavioral context by disclosing that it queries Azure DevOps Code Search in real-time for custom extensions not yet in the KB, which signals a live external lookup beyond a local cache.

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 convey the full scope, the real-time search behavior, and the critical usage rule without any filler. The most important directive is front-loaded and emphasized with 'ALWAYS.'

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 search tool with one parameter, the description covers purpose, data sources, scope, and usage context. It lacks an explicit description of the return format, but the absence of an output schema is partially mitigated by the clear 'find all...' phrasing.

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 already provides 100% coverage for the single baseObjectName parameter, including concrete examples. The description adds no additional parameter-level detail beyond referring to a 'base object,' so the schema carries the semantic weight.

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 has a specific verb and clear resource: it finds extension objects, CoC classes, and event handlers for a named base object. It is unambiguous about scope, though it does not explicitly differentiate itself from the sibling tool find_event_handlers, which overlaps with part of its functionality.

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 a strong, explicit usage directive: 'ALWAYS call before creating a new extension — avoid parallel customizations.' This tells the agent when to use the tool, but it does not mention alternatives or when not to use it, so it stops short of full 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?

The description adds important behavioral context beyond the readOnlyHint and idempotentHint annotations: the operation is EXPENSIVE and performs a full index scan over O(1M+ chunks). It also discloses automatic normalization of label ID forms (`@SYS124480` vs `@SYS:124480`), which is not visible in annotations or schema. No contradiction exists between the description and 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 dense but every sentence earns its place: purpose, use case, cost warning, alternative routing, label behavior, and an exclusion. The most critical facts are front-loaded, and 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 tool with no output schema, the description provides sufficient context to select and invoke it correctly: what it searches, why to use it, how expensive it is, when to prefer an alternative, and how label IDs are handled. The parameter schema fills in limits and defaults, leaving no critical gap.

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

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

The schema already covers all three parameters with detailed descriptions, so the baseline is 3. The description adds value by clarifying that the `name` parameter accepts not only object/method names but also fields and label IDs, and by explaining the dual label ID forms. This goes slightly beyond what the schema alone provides.

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 full index scan for all usages of an object, method, field, or label ID. It clearly distinguishes itself from sibling tools by naming find_callers and find_extensions as different alternatives. This leaves no ambiguity about what the tool does.

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 when to use this tool (impact analysis before changing or deleting an object) and when not to use it (NOT for extensions only — use find_extensions). It also names the preferred alternative, find_callers, with the condition that the XRef index is loaded. This is excellent routing guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds meaningful behavioral detail beyond that: it returns both outgoing and incoming relations, delegates to get_relation_graph when the relation index is loaded, and is O(1) in that case. This gives the agent an accurate mental model of cost and internal behavior.

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

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

Three sentences, no filler. The core return behavior is front-loaded, followed by the usage condition and an explicit anti-duplication warning. Every sentence earns its place.

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

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

For a read-only lookup tool with one well-documented parameter, the description provides everything needed to select and invoke it correctly: what it returns, when to call it, and how it relates to get_relation_graph. The absence of an output schema is mitigated by specifying the relation categories returned.

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 fully covers the only parameter, objectName, including an example. The description adds no new parameter-level semantics, which is acceptable because schema coverage is 100%; 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?

The description names a specific verb ('Returns') and a precise resource scope: ALL FK/DeleteAction/DataSource relations (outgoing) plus back-references (incoming). It clearly distinguishes itself from siblings like get_relation_graph and find_references by defining both direction and relation types.

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

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

It explicitly states when to call this tool: 'Call BEFORE generating multi-object code to understand the full dependency graph.' It also warns the agent not to call both find_related_objects and get_relation_graph for the same object, making the usage boundary concrete.

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 idempotentHint=true, and the description is consistent with them (no contradiction). Beyond annotations, it discloses valuable behavioral traits: bidirectional edge traversal, shortest-path guarantee, the specific edge kinds included (FK, DeleteAction, DataSource, Extension, Security), token-light output that never returns full object source, and O(1)-per-node BFS cost. This materially helps an agent reason about cost and output size before invoking.

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

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

Well front-loaded with the WHEN clause, and every sentence earns its place: triggers, mechanism, output format, token-light note, complexity, and sibling routing. It is slightly long due to the trigger-phrase list, but that list directly aids an agent's selection matching, so the length is justified.

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 properly conveys the return shape ('chain of object names + edge kinds'), and annotations cover the safety profile. It is missing edge-case behavior for what happens when no path exists within maxDepth or when source/target are identical or unreachable, but this is a minor gap against an otherwise rich definition.

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 fully documents source, target, maxDepth, and maxPaths with defaults and bounds. The description adds only loose context ('multiple hops', 'SHORTEST path'), not operational detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource combination ('Walks the pre-computed relation graph... returns the SHORTEST navigation path(s)'), which is far more precise than the name alone. It explicitly differentiates from the sibling get_relation_graph: full neighbourhood of one object vs. multi-hop traversal between two known objects.

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?

Opens with a WHEN clause stating the exact condition ('you need to know HOW two AOT objects are connected') and gives concrete trigger phrases in two languages. It also names the alternative explicitly ('Use get_relation_graph for the full neighbourhood of a single object; use this to traverse multiple hops between two known objects'), leaving no selection 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context beyond that by explaining how similarity is determined (same kind, method set, field set), which shapes an agent's expectations about results. There is no contradiction between the description and 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 with no filler. The primary action and similarity criteria are front-loaded, and the use case is provided in a compact second sentence. 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 simple read-only search tool with full schema coverage and safety annotations, the description is complete. It explains what the tool finds, how similarity is judged, and when to use it. No output schema is present, but the return semantics ('find objects') are clear enough 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?

Schema description coverage is 100%, so the schema already documents objectName, maxResults, and filterAotType adequately. The description adds no parameter-specific semantics beyond referring to 'the one you supply,' so it does not need to compensate. Baseline 3 is appropriate.

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

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

The description uses the specific verb 'Find' with a clear resource: D365 objects structurally similar to a supplied object. It further defines what 'structurally similar' means (same kind, similar method set, similar field set), which distinguishes it from siblings like compare_objects or find_related_objects. The utility statement about reference implementations makes the intended 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 provides a clear usage trigger: 'Useful when you need a working reference implementation to copy from.' It conveys when to use the tool but does not explicitly name alternatives or state when not to use it. Most agents can infer the boundary against comparison/similarity tools, but the guidance is not fully explicit.

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 idempotentHint=true, and the description reinforces this by saying the tool 'returns' suggestions and patches rather than applying changes. It openly discloses the external Ollama dependency, the required OLLAMA_HOST, the model name, and the fallback behavior when Ollama is unavailable.

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 primary use case. Trigger phrases add a bit of length but help with selection. It remains information-dense without being bloated.

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

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

For a moderate-complexity tool with annotations and full schema coverage, the description covers the key context: triggering condition, return content, Ollama dependency, and fallback. It does not detail the exact response structure, but the described output shape is probably sufficient 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?

Schema coverage is 100%, so the schema documents all parameters. The description adds meaningful semantics beyond the schema, especially for generatePatches, by naming the model (ALMXPP_SUMMARIZE_MODEL), the Ollama requirement, and the fallback to built-in suggestions. Other parameters are adequately covered by 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 purpose: return BP violations with fix suggestions and AI-generated X++ patches. It explicitly frames the tool as a follow-up to validate_best_practices, which distinguishes it clearly from the closest sibling and from other fix/suggestion tools.

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

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

The description gives a clear precondition ('WHEN: validate_best_practices returned violations') and explains when Ollama should be used via generatePatches. It does not explicitly list when not to use the tool or name alternatives beyond validate_best_practices, but the context is strong.

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

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

With readOnlyHint=true already signaling no mutation, the description adds meaningful behavioral context by detailing what is produced: complete AxDataEntityView XML with data sources, field mappings, entity key, IsPublic/PublicEntityName, and staging table template. It also notes the use of real field names and relations from the local model.

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

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

The description is front-loaded with the WHEN trigger, then output details, then the critical prerequisite. The trigger phrase list is long but serves a useful routing purpose; overall, every sentence contributes information without meaningless 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 6-parameter tool with no output schema, the description covers the artifact produced, its contents, the source model, and the mandatory pre-check. It is sufficient for correct invocation, though it could add a note about what happens if a standard entity already 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 input schema already documents all six parameters well. The description adds some context around IsPublic/PublicEntityName and field mappings, but it does not materially extend the schema's parameter-level explanations.

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 generates AxDataEntityView AOT XML from a table for OData/DMF/data migration, with a specific resource and output type. It also differentiates this from siblings like get_data_entity_info and create_aot_object by naming the exact XML artifact and use case.

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 states WHEN to use it, provides concrete trigger phrases, and instructs 'ALWAYS call find_entity_for_table first to verify a standard entity doesn't already exist.' This gives clear routing and an explicit alternative/check before using the tool.

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 idempotentHint=true, lowering the bar. The description adds useful behavior: diagrams render in Copilot Chat, Cursor, Claude, and markdown viewers, and it discloses that 'flow' is disabled because 'static call trees are misleading in D365 due to CoC and event handlers'. This context goes beyond the schema and annotations without contradicting 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?

The description is longer than average but tightly structured with labeled sections (WHEN, triggers, types, note). Every sentence earns its place, and the flow-disabled note prevents wasted calls. The trigger enumeration is somewhat verbose but directly serves the agent-routing purpose.

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-required-param diagram tool with readOnly/idempotent annotations, this is complete: it covers when to use, what it produces, where output renders, valid input values, the alternative sibling, and a disabled value. The absence of an output schema is compensated by explicitly stating the Mermaid output format.

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 baseline is 3. The description adds meaning by expanding diagramType semantics — 'er' as 'entity-relationship diagram for a table and its relations' and 'security' as the Role->Duty->Privilege->EntryPoints chain — and by revealing that methodName is unused. This exceeds what the schema alone communicates.

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: 'Generate visual Mermaid diagrams from D365 F&O knowledge base data' for 'table relationships or security chains'. It explicitly distinguishes itself from the sibling `trace_security_chain`, so an agent can reliably separate it from nearby tools like `generate_security_report` or `get_relation_graph`.

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 'WHEN:' clause plus explicit trigger words ('generate diagram', 'diagramme', 'ER diagram') tell the agent exactly when to fire. It gives when-not guidance too: 'for the structured text chain with tables of duties/privileges/entry-points use `trace_security_chain` instead', and flags that 'flow' is disabled — no inference required.

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 readOnlyHint annotation already covers the safety profile, and the description adds transparency about what the generated FDD includes (Purpose, Business Context, Data Fields with resolved labels, Business Rules, etc.). It also states the output is 'ready for review and sign-off,' which implies a structured, human-ready deliverable. No contradiction with the annotation; overall the description enriches behavioral understanding.

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 structured and front-loaded with WHEN, but it contains redundancy: the 'WHEN' paragraph and the 'Triggers' paragraph list overlapping examples. The all-caps 'FUNCTIONAL DESIGN DOCUMENT GENERATOR' acts as a title and adds some clutter. It's not overly long, but every sentence doesn't earn its place due to 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 relatively simple generator with 3 parameters and no output schema, the description covers the essential context: when to use it, what it produces, the sections included, and the alternative for technical docs. It doesn't describe the return format (e.g., markdown vs plain text), but that is a minor gap given the clear output description. Overall the tool is well contextualized.

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 all three parameters adequately. The description adds minimal parameter-level meaning beyond the schema; it hints at 'resolved labels' as part of the generated document but doesn't explain how parameters affect output. Baseline 3 is appropriate because 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?

The description clearly states a specific action: generating a Functional Design Document, and lists the exact document types (FDD, functional spec, CdC, cahier des charges). It differentiates itself from get_object_details by warning that it is NOT for technical developer docs. The description also enumerates the sections generated, making the tool's purpose unambiguous.

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

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

The description provides explicit when-to-use guidance with trigger phrases, and an explicit exclusion: 'NOT for developer technical docs -- use get_object_details for that.' This directly routes the agent to the correct sibling tool when the request is technical rather than functional. The trigger list is highly actionable and covers multiple language variants.

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 readOnly and idempotent, and the description adds substantial behavioral context beyond that: it 'uses real field names, relations, and indexes from the knowledge base', returns 'side-by-side X++ and SQL with explanations', and explicitly states the generated X++ is 'a template -- adapt it to your custom code context before using in production.' This goes well beyond the annotations and helps the agent set correct expectations.

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 longer than average, but the length is justified by trigger phrases, capability list, and critical usage caveats. It is front-loaded with the WHEN clause and important notes. It could be tightened slightly by trimming some redundant trigger examples, but every major section 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 tool with 8 parameters, no output schema, and readOnly/idempotent annotations, the description covers what is needed to call it correctly: capabilities, parameter interactions via natural language, join dependency on find_related_objects, output format, and production-readiness caveat. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the input schema already documents all 8 parameters. The description summarizes capabilities such as 'multi-table joins (auto-detects relations)', 'WHERE filters', 'ORDER BY', 'TOP/firstonly', and 'cross-company', but it does not add deeper syntax or format details beyond the schema. Baseline 3 is appropriate.

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?

Description states a specific verb and resource: generate 'X++ select statements and equivalent T-SQL queries for D365 F&O tables'. It clearly distinguishes from siblings like generate_xpp_template or generate_data_entity by focusing on query generation with real field names, relations, and indexes.

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

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

Provides explicit WHEN triggers like 'X++ select', 'generate a query', 'SQL for', and 'join with', making it clear when this tool is intended. It also gives a mandatory precondition for multi-table joins: 'call find_related_objects (or get_relation_graph if the relation index is loaded) FIRST' — strong routing and sequencing guidance, plus a warning to adapt generated X++ before production use.

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 readOnlyHint=false annotation, the description discloses that the tool performs no LLM reasoning, generates two document formats, and returns download URLs. This gives the agent a clear model of the tool's side-effect-free rendering behavior, though it does not elaborate on storage duration or access control for the generated files.

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 critical precondition, followed by the output format and the no-LLM behavior. Every sentence carries essential information with 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 an 8-parameter tool with no output schema, the description covers the overall workflow, input provenance, output types, and the key constraint that reasoning must happen before invoking this tool. It could mention error cases or how to handle the returned URLs, but the clear pipeline context and full schema coverage make it sufficiently complete for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that fields like v1, v2, customModelLabel, and counts should be echoed from prepare_release_note_context, but most parameter-level meaning is already in the schema. The findingsJson schema is documented in the input schema, so the description does not need to repeat it.

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

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

The description uses a specific verb ('renders') and a clear resource (the findings array) into concrete outputs: Word .docx appendix and PowerPoint .pptx executive summary, returning download URLs. It is clearly distinguished from prepare_release_note_context, which produces the context rather than rendering the final documents.

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 states the precondition: call prepare_release_note_context first, analyze its objects array, and produce the findings JSON per the instructions field. It also warns that the tool does NOT call an LLM itself, so the agent knows not to delegate reasoning to this tool.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds non-obvious behavioral context by explaining that the report surfaces orphan duties/privileges that grant no real access and includes inferred license tiers. This goes beyond what the annotation alone provides, though it does not mention output format or performance implications.

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, no filler, with the main purpose front-loaded in the first sentence and useful specifics in the following two. Every sentence earns its place.

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

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

Without an output schema, the description does a good job of explaining what the generated report contains. It covers model scoping, the per-role breakdown, license-tier inference, and orphan detection. It stops short of describing the exact output structure or delivery mechanism, but for an optional-parameter read-only report tool this is close to 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 filterModel and maxRolesDetail are already well documented in the input schema. The description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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 ('Generate'), a specific resource ('security & licensing governance report'), and the exact contents of the report: roles, duties, privileges, entry points, and inferred license tiers. This clearly distinguishes it from sibling security tools by emphasizing the governance-report angle and the orphan-duty detection.

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: use this when you need a governance report for indexed models. However, it does not explicitly say when to choose this over related siblings like get_security_coverage_for_object or trace_security_chain, and it offers no when-not-to-use guidance.

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