ALM X++ MCP Server

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

Annotations only declare readOnly/idempotent/open-world/non-destructive; the description adds substantial behavior: it reads un-merged source via the ADO REST API, analyses against the indexed standard KB, embeds source when includeSource is true, acknowledges the BP engine's X++-centric limitation for AOT XML, and states the required scope (DEVOPS_ORG_URL + DEVOPS_PAT with Code:Read). 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 front-loaded with a priority trigger and organized around numbered analysis steps, so an agent can quickly identify the tool's purpose. It is long and contains some redundant warnings ('DO NOT fall back' vs 'NEVER run git'), but nearly every sentence carries operational or selection 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?

Despite having no output schema, the description fully covers the input preconditions, the method, the returned content (source and four concrete analysis outputs), and the follow-up action (ado_post_pr_comment requiring user confirmation). This gives an agent enough context to invoke and interpret the tool correctly for a complex PR analysis.

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 detailed per-parameter docs, so the baseline is 3 and the description need not compensate. The description repeats context for includeSource but contributes little new meaning for prId, repositoryId, maxFilesDeep, or sourceCharsPerFile; the 'FULL source' claim is also tempered by the sourceCharsPerFile truncation rule in the schema.

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

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

States a clear, specific purpose: 'Analyse the full D365 F&O code impact of a Pull Request,' with enumerated outputs (BP validation, upgrade impact, extension conflicts, review comment). It also explicitly frames itself as the tool to use for PR review and names search_d365_code as the tool to avoid, so its scope is unambiguous against at least the most likely sibling.

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 unusually explicit trigger phrases, a hard 'NEVER' exclusion for search_d365_code, and direction not to use local git workflows or to call ado_post_pr_comment afterwards. However, it does not disambiguate from the closely named sibling ado_review_xpp_pr, which likely occupies the same PR-review space, leaving some potential 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=true, idempotentHint=true, and destructiveHint=false; the description adds genuine behavioral context beyond this: the tool returns raw structured context only (not a finished analysis), it requires DEVOPS_ORG_URL + DEVOPS_PAT, and it defines the post-call synthesis obligation including the comment-posting restriction. No contradiction with the annotations exists — 'Fetch and assemble' is consistent with readOnly/idempotent.

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 (~350+ words) but well-structured with headers and front-loaded with purpose, triggers, and exclusions. There is noticeable redundancy: the 'no emojis / sans icônes' constraint appears twice, and the posting restriction is stated both in section 5 and again in the IMPORTANT sentence. The extensive 'YOUR JOB AS COPILOT' section partially substitutes for the missing output schema, but could be tightened.

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 return contents (metadata, KB object details, custom code, relation graph), required environment variables, exclusions, and the expected downstream synthesis in French. Notable but not fatal gaps: no contrast with the close sibling ado_analyze_pr_impact and no error/edge-case behavior (e.g., work item not found, missing env vars). Overall it is complete enough for an agent to invoke and use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline 3 applies and the schema already documents all six parameters well (e.g., focusObjects notes it 'speeds up analysis significantly', includeImages notes latency and token cost). The description adds no parameter-level meaning beyond the schema — it neither clarifies formats nor adds missing semantics. This is acceptable given the rich schema, but the description itself contributes nothing 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?

The opening line states a specific verb+resource: 'Fetch a Work Item and assemble ALL technical context needed for D365 F&O expert analysis.' The NEVER-for clause explicitly carves out labels, X++ code lookup, and AOT objects, routing those to search_labels/search_d365_code, which distinguishes it from those siblings. However, it does not contrast with close analysis siblings like ado_analyze_pr_impact or data-retrieval siblings like ado_query_workitems, so differentiation is only partial.

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 list ('analyse le workitem', 'read the work item', '#1234', 'WI#') and an explicit NEVER-for list naming alternatives (search_labels / search_d365_code). It also constrains post-call behavior by forbidding ado_post_comment on any linked/related work item. Selection conditions and exclusions are fully spelled out with nothing left to inference.

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

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

The description richly discloses behavior beyond the annotations: automatic Git branch creation, the three-case naming convention logic (A/B/C), the N counter increment behavior, assignee/CC embedding in the task description, the French/English language rule, and credential requirements (DEVOPS_ORG_URL + DEVOPS_PAT with specific permissions). readOnlyHint=false is consistent with a create operation; no contradiction.

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

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

The description is long but earns its length given the tool's complexity (10 parameters, three naming branches, language rule, auth requirements). It is well-structured and front-loaded with WHEN triggers before rules and requirements. Minor redundancy exists in repeating trigger examples and the naming convention explanation, but no sentence is wasted.

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

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

For a high-complexity tool with no output schema, the description covers usage, naming behavior, branch creation, language handling, and credentials. The main gap is that it never states what the tool returns (task ID, branch name, URL), which an agent would need to continue a workflow after creating the task.

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 10 parameters, warranting the baseline of 3. The description adds indirect context—naming rules depend on the parent work item (workItemId) and assignee/CC get embedded in the description—but it does not add per-parameter semantic detail 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 states a specific verb and resource: 'Create a D365 F&O development Task work item in Azure DevOps following the project naming convention.' It also includes concrete trigger phrases ('create task', 'start development on', 'créer une tâche') that make selection unambiguous. The create-vs-update distinction is clear against siblings like ado_update_workitem.

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 with trigger phrases ('create task', 'créer une tâche', 'start development on', etc.), which is strong usage direction. It does not explicitly name alternatives to avoid or when-not conditions, but the trigger listing plus the creation-oriented rules make the intended invocation context clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds non-redundant behavioral context: it uses 'KB signals ... combined with ADO history' and returns a per-phase breakdown, confidence level, and risk factors. 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 structured with WHEN, PRIORITY TRIGGER, purpose, returns, and trigger phrases, which makes it scannable. It is slightly redundant because the WHEN section and the final Triggers list mostly repeat the same example phrases, but overall it stays reasonably lean.

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

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

For a 3-parameter tool with no output schema, it fully describes what the estimate is based on, what is returned (phase breakdown, KB signals, confidence, risk factors), and how the output can be used. An agent can select and invoke this tool correctly with the information provided.

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 workItemId, project, and focusObjects. The description mentions Work Item IDs via trigger examples but adds no meaning beyond the schema for parameters like focusObjects or project fallback.

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

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

The opening 'EFFORT ESTIMATOR -- Estimate D365 F&O development effort for a Work Item' states a specific verb, target resource, and domain. It is clearly differentiated from sibling tools like ado_analyze_workitem by focusing on hour estimates and phase breakdowns rather than general 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?

It gives explicit WHEN triggers ('user asks for an effort estimate, chiffrage, or development hours') and a priority instruction to call AFTER ado_analyze_workitem. It does not explicitly state when not to use the tool or name mutually exclusive alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description is not burdened with basic safety disclosure. It adds useful behavioral context: extension lookup only happens if D365_CUSTOM_MODEL_PATH is set, and the tool returns a structured analysis including standard objects, effort estimate, and reasoning. No annotation contradiction exists.

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

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

The description is dense and front-loaded with WHEN, followed by classification definitions, return sections, triggers, and an input-mode caveat. It is somewhat long and the WHEN section overlaps with the later Triggers list, but every section carries useful information for a complex classifier 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?

There is no output schema, so the description must explain return values, and it does: detected domain, standard objects, existing extensions, effort estimate, and reasoning. It also covers all four input modes (project, workItemId, requirements, requirementText) and their relationships, making the tool safely callable without external documentation.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful usage nuance: it explains that requirements overrides WI and requirementText, and that requirementText should be preferred when a WI was already analyzed. This goes beyond the schema's individual parameter descriptions and helps an agent choose the correct parameter combination.

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 identifies itself as a 'GAP / FIT CLASSIFIER' that analyzes D365 F&O requirements and classifies them into four defined verdicts. This immediately distinguishes it from generic work item analysis tools like ado_analyze_workitem and effort-only estimators.

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 trigger phrases, states when the tool is relevant ('Also triggered by gap analysis or fit/gap classification'), and gives a concrete routing rule: if a work item was already analyzed by ado_analyze_workitem, pass requirementText directly and do NOT re-fetch with workItemId. This is actionable guidance for choosing the right input mode.

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 and idempotentHint annotations, the description discloses the fallback behavior when repositoryId is unknown, the required credentials and scope (DEVOPS_ORG_URL + DEVOPS_PAT with Code: Read scope), and the returned fields. This adds meaningful behavioral context that annotations alone do not 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 longer than average but every sentence earns its place: trigger phrases, an explicit alternative exclusion, core functionality, repositoryId handling, filters, return values, related tool, and auth requirements. The priority trigger is front-loaded, ensuring the agent immediately knows when to call 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 list PR tool with six fully documented parameters and no output schema, the description is complete. It covers invocation triggers, filtering options, repositoryId behavior, expected return fields, authentication needs, and the natural follow-up tool. Nothing essential for an agent to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantics beyond the schema: it explains how to handle an unknown repositoryId (omit it to list all repositories) and clarifies the filter semantics (status, author display name, target branch). This nudges it above the baseline, though it doesn't add details for every parameter.

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

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

The description starts with a specific verb and resource: 'List Pull Requests in an Azure DevOps Git repository.' It also states the exact output (PR ID, title, author, source->target branch, review status, linked work items, creation date) and clearly distinguishes itself from search_d365_code and ado_analyze_pr_impact. This makes the tool's 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?

The description provides an explicit priority trigger list of user phrases and a direct exclusion: 'NEVER call search_d365_code for PR listing requests.' It also routes follow-up analysis to ado_analyze_pr_impact. This is outstanding guidance for when to use the tool versus 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?

Discloses that this is a write operation requiring DEVOPS_PAT with Work Items: Write permission, warns confirmation is needed, and clarifies it should be called after analysis. Annotations confirm readOnlyHint=false and destructiveHint=false, and the description adds meaningful context beyond the annotations.

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

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

Information is front-loaded with WHEN and PRIORITY TRIGGER labels, then the confirmation warning and workflow. Slightly long but every sentence serves a purpose, and the structured labels make it 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?

Covers when to use, prerequisites, workflow, permissions, and parameter source. No output schema exists and none is needed for a simple write operation. Lacks a note about idempotency or duplicate comments, but the provided context is otherwise sufficient.

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 parameters are already documented. Description adds valuable semantic context: the commentText should be the ready-to-post block from `ado_analyze_workitem`, and project falls back to DEVOPS_PROJECT env var. Slight extra value beyond 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?

Description explicitly states the action: post, add, or save a comment to an ADO Work Item. Distinguishes itself from sibling `ado_post_pr_comment` by targeting Work Items specifically, though it could be clearer about that exact difference.

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 trigger, PRIORITY TRIGGER conditions, a recommended workflow with step-by-step sequencing, a warning to always ask for user confirmation, and required permissions. This is exemplary 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?

Goes beyond annotations by disclosing that explicit user confirmation is mandatory, and that DEVOPS_ORG_URL and DEVOPS_PAT are required with Pull Request Threads Read & Write permission. 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?

Well-structured and front-loaded with the WHEN condition, then the warning and workflow. A bit verbose, but every sentence carries actionable guidance 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?

Covers when to use, prerequisites, confirmation requirement, and the full recommended workflow. It does not describe the return value, but that is not essential for correctly invoking this write operation.

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 applies. The tool description itself adds little parameter detail beyond the overall action, though the schema already documents each field adequately.

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?

Uses a specific verb and resource: 'post, add, or save a review comment to an ADO Pull Request.' It also states the WHEN condition and names the related analysis tool, making it easy to distinguish from the generic sibling ado_post_comment.

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 triggers, including example user phrases, and a recommended confirmation workflow that requires calling ado_analyze_pr_impact first and asking the user before posting. This is strong routing guidance with no 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=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: it requires DEVOPS_ORG_URL + DEVOPS_PAT with Code: Read scope, computes a topological merge order, and detects branch-chain relationships. This gives a fuller picture of what the tool actually does 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 long but well-structured: purpose first, then per-PR behavior, output sections, triggers, and prerequisites. The trigger list is somewhat extensive, but it earns its place by helping an agent recognize the right invocation context. Slightly tighter wording could improve it, but it is not wasteful.

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 correctly enumerates what the tool returns: per-PR object table, conflict matrix, dependency graph summary, and ordered merge sequence. It also covers the two core analysis dimensions and the required credentials. Given the tool's complexity, this is a reasonably complete definition, though it could mention behavior on empty or invalid PR sets.

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 five parameters. The description adds no extra parameter-level semantics beyond what the schema provides; it focuses on behavior and output. This matches the baseline of 3 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: 'Scan multiple Pull Requests and build a cross-PR dependency graph'. It clearly distinguishes itself from sibling tools like ado_list_prs or ado_analyze_pr_impact by focusing on cross-PR dependency analysis, object conflicts, and merge ordering.

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 Triggers section with concrete natural-language phrases ('PR dependencies', 'ordre de merge des PR', 'conflits entre PR') that tell an agent when this tool is appropriate. It does not explicitly name alternatives or list when-not-to-use conditions, but the trigger list gives clear contextual 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, but the description adds valuable operational context: it requires DEVOPS_ORG_URL and DEVOPS_PAT env vars, returns a maximum of 50 items, and specifies the returned fields. It also discloses behavioral scope by restricting the tool to Azure DevOps and excluding labels/code scenarios.

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 and front-loaded with purpose and scope, followed by triggers, exclusions, shortcuts, and constraints. It is long and somewhat noisy, but nearly every sentence carries routing or usage information, so it earns its 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?

Given the tool has 11 parameters with 100% schema coverage and no output schema, the description still provides the missing return shape (ID, title, type, state, priority, area, assigned-to), a result cap, env var prerequisites, and explicit usage patterns. Nothing critical is left unexplained.

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 goes beyond the schema by explaining what each shortcut expands to ('bugs' = all active bugs, 'my bugs' = assigned to me, 'recent' = updated last 7 days, 'sprint' = current iteration), which meaningfully aids parameter use.

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 verb-resource pair: 'Query Work Items ... in Azure DevOps' and names the work item types covered. It is unambiguous about scope ('AZURE DEVOPS ONLY') and clearly distinct from sibling tools that create, update, or analyze work items.

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 trigger keywords, explicit never-use cases, and named alternatives ('For labels -> use search_labels', 'For D365 code -> use search_d365_code or get_object_details'). This gives an agent strong routing guidance beyond the tool name.

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

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

Beyond the readOnlyHint annotations, the description discloses important behavioral details: supported formats and their exact return representations, max attachment size (25 MB), image size limit (4 MB), the fallback behavior for unsupported binary formats, and environment variable requirements. This richly supplements the annotation layer without contradicting it.

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 every sentence earns its place: purpose, trigger conditions, prerequisites, format-specific behavior, limits, and env vars. The critical purpose is front-loaded, and the dense format list replaces the need for an output schema. 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?

Despite having no output schema, the description fully covers return behavior for every supported format, explicitly lists unsupported formats, states size limits, and notes the required environment variables. An agent has everything it needs to decide whether to call this tool and what to expect from the response.

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's parameter-related details (fileName case-insensitivity, sheetName default, project env fallback) largely repeat what the schema already states. It adds useful context for fileName ('as shown by ado_analyze_workitem') but does not significantly elevate understanding 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 opens with a precise verb and resource: 'Reads the ACTUAL CONTENT of a file attached to a work item.' It enumerates supported formats and return behavior, making the tool's scope unmistakable and distinguishing it from sibling tools like ado_analyze_workitem, which is referenced only as a prerequisite for discovering filenames.

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 provides a 'WHEN' clause, concrete trigger phrases, and a clear prerequisite ('Call ado_analyze_workitem first'). It also states what the tool does NOT parse, giving the agent an exclusion boundary for unsupported formats. This is as explicit as usage guidance gets.

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 this read-only and idempotent, and the description adds significant behavioral detail: it fetches source from the PR branch with fallback to the indexed version and announces when that fallback occurs, explains why xppbp.exe cannot run (PR is uncompiled), and notes the deterministic rule set used. It also discloses required credentials and dependencies. 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 front-loaded with 'WHEN', then flows logically through output, limitations, trigger phrases, prerequisites, and follow-up action. While lengthy, every sentence carries useful information for tool selection and invocation; the trigger examples aid intent recognition and the technical caveats are essential for correct use. 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 tool with this complexity—requiring Azure DevOps credentials, XRef index, D365-specific analysis, and interplay with sibling tools—the description covers prerequisites, fallback behavior, output structure, and integration points. The absence of an output schema is mitigated by naming the exact dimensions of review (blast radius, BP violations, impact severity). 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 baseline is 3. The description does not elaborate on individual parameters, but the schema already documents prId, project, repositoryId, and maxDeepAnalysis clearly. The description's mention of 'each changed object' and fallback behavior adds context but not parameter-level semantics, so it neither improves nor degrades from baseline.

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

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

The description opens with a specific verb and resource: reviewing a PR that modifies X++ code or AOT objects and returning a structured code review. It clearly differentiates itself from siblings like find_error_patterns and find_callers by specifying that it produces D365-specific PR review insights covering blast radius, best-practice violations, and impact severity.

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:' prefix explicitly states the exact conditions for use, and it names find_error_patterns as the alternative for Microsoft rule text. It also mentions combining with ado_post_pr_comment for posting findings, giving the agent a clear workflow. This goes beyond generic context and provides actionable routing.

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

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

Beyond the annotations, the description adds important behavioral context: the need to always show the user what will be changed and ask for confirmation, and the prerequisite of DEVOPS_PAT with Work Items: Write permission. These details help the agent understand safety and authorization requirements that annotations alone do not convey.

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

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

The description is dense but efficient: it front-loads the core purpose, then covers supported fields, trigger phrases, safety behavior, and authorization in a concise, scannable format. 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 three-parameter update tool with annotations and a fully documented schema, the description is complete: it explains what the tool updates, how fields are selected, when to trigger it, how to handle confirmation, and what permissions are required. No output schema exists, and the description does not need to explain return values for this mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces that fields use Field Reference Names and can be standard or custom, but it largely duplicates the examples already present in the fieldsJson parameter description rather than adding substantial new parameter-level 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 clearly states the specific action ('Update one or more fields on an existing Azure DevOps Work Item') and identifies the resource. It distinguishes itself from sibling tools like ado_create_task by explicitly targeting existing work items, and from read/query tools by the update verb.

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

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

The description provides clear context for when to use this tool, including user trigger phrases and the requirement to show changes and get confirmation before calling. However, it does not explicitly state when not to use it or name alternative tools such as ado_create_task for new work items, so it falls just 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?

The description adds substantial behavioral context beyond the annotations: it discloses the tool replaces the ENTIRE page body and does not merge/append, it documents ETag-based concurrent-edit safety handling, and it states the required env vars and PAT scope (Wiki: Read & Write). This is exactly the kind of destructive-context and auth detail an agent needs. No contradiction with readOnlyHint=false, destructiveHint=true, or idempotentHint=true.

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

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

Four dense sentences, each earning its place: scope constraint, core action, critical edit-vs-replace warning, concurrency safety, and auth prerequisites. The most decision-relevant information is front-loaded ('AZURE DEVOPS ONLY', create/overwrite, call get_page first). Zero fluff or repetition of schema 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?

For a destructive write tool, the description covers everything an agent needs to select and invoke it correctly: prerequisites (env vars + PAT scope), safety mechanism (ETag), destructive scope (entire body replaced), and routing to sibling tools. All four parameters are documented in the schema. The only omission is return-value format, which is minor for an upsert tool and not required given no 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 description coverage is 100%, so the baseline is 3 — the schema already documents all four parameters with examples, fallback behavior, and disambiguation guidance. The description adds minimal parameter-specific meaning beyond the schema, only lightly reinforcing that content is 'new markdown content.' It does not need to compensate, so 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 ('Create a new wiki page, or OVERWRITE an existing one with new markdown content') tied to a concrete resource. It also distinguishes itself from sibling tools by explicitly naming ado_wiki_get_page as the tool to call first for edits, and the scope constraint 'AZURE DEVOPS ONLY' anchors it against non-DevOps 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?

Explicit when-to-use guidance is present: 'ALWAYS call ado_wiki_get_page first if you intend to edit (not replace) an existing page's content.' This routes the agent to the correct alternative with a clear condition. It also routes to ado_wiki_list for the wikiIdentifier disambiguation case. This is model-level 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 already mark the tool as destructive, idempotent, and non-read-only. The description adds important behavioral detail beyond those hints by revealing the cascading deletion of sub-pages and the exact authentication requirements. 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?

Two sentences, with the most important constraints (scope, deletion behavior, prerequisites) front-loaded. Every sentence adds necessary information and there is no filler or repetition of schema 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?

For a destructive tool with no output schema, the description provides the essential context: platform restriction, destructive cascade, and required credentials. It could mention what happens on success or error, but the prerequisites and behavior are sufficiently covered 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 all three parameters, including defaults and fallback behavior. The description does not add parameter-level detail beyond the schema, which is acceptable given full 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 names a specific verb ('Delete') and resource ('wiki page') and states that sub-pages are also deleted. It clearly distinguishes this from sibling tools like ado_wiki_get_page and ado_wiki_create_or_update_page by describing a destructive operation rather than a read or write.

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

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

The description makes the Azure DevOps-only scope explicit and lists required environment variables plus PAT scopes. It doesn't explicitly name alternatives like ado_wiki_create_or_update_page for edits, but the destructive purpose and prerequisites provide clear context for when this tool should be used.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it requires DEVOPS_ORG_URL and DEVOPS_PAT, uses page-path syntax, and reads immediate sub-page paths. No annotation contradiction 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?

Single sentence with no filler. The environment constraint, main action, path syntax, and auth requirements are all front-loaded and each contributes necessary 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?

Given rich annotations and full schema coverage, the description covers the essential context: environment, auth, path syntax, and behavior. With no output schema, it leaves the exact return format unspecified, but 'Read the content' is sufficient for a simple read operation.

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 baseline is 3. The description repeats path syntax examples already present in the schema and adds no additional meaning for project, wikiIdentifier, or includeSubPages.

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 read verb and resource: 'Read the content of a wiki page'. The Azure DevOps-only qualifier and the mention of immediate sub-page paths further scope the operation. It does not explicitly distinguish itself from ado_wiki_list, but the read/get semantics make the purpose clear.

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

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

Provides clear usage context: Azure DevOps only, required env vars, and wiki page-path syntax. It does not explicitly name alternatives or say when not to use this tool, but the read action naturally separates it from the create/update/delete wiki siblings.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds useful context beyond annotations: the tool depends on specific env vars, targets Azure DevOps specifically, and its result set includes both project wikis and published code-as-wiki repos. No contradictions 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?

Every sentence earns its place: scope warning, purpose with detail, explicit usage guidance, and environmental requirements. It is front-loaded with 'AZURE DEVOPS ONLY' and contains 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 simple list operation with one optional parameter, rich annotations, and clear usage guidance, the description is complete. It explains when to use the tool, what it returns conceptually, and what environment setup is needed. No critical information is missing.

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

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

Schema description coverage is 100%: the only parameter, project, is fully described with its optionality and fallback to DEVOPS_PROJECT env var. The tool description does not add parameter-level detail, but the schema already carries that burden, so the baseline 3 applies.

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

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

The description uses a specific verb ('List') and resource ('all wikis in a project'), and elaborates on what counts as a wiki ('project wiki plus any published code-as-wiki repos'). This clearly distinguishes it from sibling wiki tools like ado_wiki_get_page or ado_wiki_create_or_update_page, which operate on individual pages.

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 tells the agent when to use it: '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.' It also gives environmental prerequisites (env vars) and an 'AZURE DEVOPS ONLY' scope, leaving no ambiguity about invocation context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral detail: it cross-references every extensibility hook, detects specific breakage categories, and returns a prioritized risk report with fixes. This goes well beyond the annotations and gives the agent an accurate model of tool execution.

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 condition and trigger phrases, then moves efficiently through scope, detection categories, and output. The trigger list is slightly redundant with the WHEN clause, but every sentence contributes usable guidance for tool selection.

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 tool with no output schema, the description covers the required input, the analysis scope, the detected failure modes, and the return format. It is mostly complete, though it could add caveats about how D365_CUSTOM_MODEL_PATH is configured or any runtime/scale limitations.

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

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

The input schema has zero properties, so the description is the only source of input semantics. It names the required D365_CUSTOM_MODEL_PATH, which is critical context beyond the empty schema, but it does not clarify the path's format, where it is resolved from, or whether it is an environment variable.

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 (analyze upgrade risk), a specific resource (custom D365 F&O model), and enumerates concrete detection targets such as Chain of Command, event handlers, and extensions. It is clearly distinguishable from sibling tools by its upgrade-version detection focus, even without naming a specific alternative.

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 (upgrading D365 F&O or applying a Microsoft update) and a rich set of trigger phrases for agent matching. It does not explicitly name alternative tools or state when not to use this tool, so it falls short of a full exclusion-based usage guideline.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context by specifying the scope ('current session') and that it affects only the cached connection, not the underlying Application Insights resource. This goes beyond the structured 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 a single, front-loaded sentence with no filler. It states the action, the target, and the scope efficiently, earning its place completely.

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 zero-parameter, no-output-schema tool, the description is complete: it explains what is removed, the session scope, and the origin of the cached connection. No critical information is missing 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?

The tool has zero parameters, so the baseline is 4. The description adds relevant context by naming the connection being cleared, which is sufficient given no parameters exist to document.

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 identifies the exact resource: the Application Insights connection cached for the current session by appinsights_set_connection. This clearly distinguishes it from sibling connection tools like d365fo_clear_connection and from the paired set_connection 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 clearly implies its usage as the counterpart to appinsights_set_connection: it clears the session-level cache that tool created. However, it does not explicitly state when to prefer it over alternatives or provide a 'use when' condition, so it falls just short of full 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 already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), lowering the bar; the description adds real behavioral context on top: the report-assembly behavior, conditional rendering of section 3 only 'if the workspace actually has data there', and the ElapsedMilliseconds convention used to flag slow events. 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?

Information is front-loaded with the WHEN purpose, and the numbered sections make the report output easy to anticipate. The trigger-phrase list is slightly redundant (the same intent repeated across languages) but earns its place for multilingual intent matching; no sentence is wasted.

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

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

With no output schema present, the description carries the burden of explaining return values — and it does: three clearly enumerated report sections with their source tables (exceptions, customEvents, requests/dependencies), the conditional empty-data behavior, and the connection prerequisite. Combined with full schema parameter ranges, an agent has everything needed to decide on and invoke 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?

Schema description coverage is 100% for all three parameters, so the baseline is 3. The description adds value beyond the schema by explaining the telemetry convention behind minDurationMs: events carrying an 'ElapsedMilliseconds custom property' (ALMMonitoring-instrumented FDDs, out-of-box signals) get the duration breakdown and 'slow' threshold. This ties the parameter to the actual data source rather than restating schema text.

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

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

Opens with a specific WHEN and a precise verb-resource pair: it diagnoses why a 'D365 F&O environment feels slow' using 'real Application Insights telemetry the environment already emits'. The three numbered report sections (exception hotspots, hot custom telemetry events, slow web requests/dependencies) concretely define the output and separate it from generic query tools like 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?

States an explicit trigger condition ('WHEN: user wants to understand/deduce why a D365 F&O environment feels slow') and names the prerequisite (appinsights_set_connection or server env vars). 'No trace file upload needed' implies an alternative that requires trace uploads, but it never explicitly names the competing sibling (e.g., detect_performance_issues), leaving a small inference step.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond this: the KQL language has no mutation operators, a connection must be configured first, and the standard App Insights schema is expected. This is valuable behavioral disclosure 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 front-loaded with the core action and then adds prerequisites, schema guidance, and sibling routing. The trigger-phrase list is slightly long but useful for selection. Minor redundancy exists with the annotations around read-only behavior, but it does not harm clarity.

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?

Covers the prerequisite, the scope, the alternative tool, and the schema family. With all parameters already documented in the schema and safety covered by annotations, the main missing piece is an explicit statement of the result shape, but for a raw query tool the returned table is fairly self-explanatory.

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 clearly, including the lookbackHours time-range behavior and maxRows limits. The description adds schema-context guidance (which tables are available) but no additional parameter-level semantics 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?

States a specific verb and resource: 'Run a raw KQL query against the D365FO environment's Application Insights / Log Analytics workspace.' It also explicitly distinguishes itself from appinsights_diagnose_slowness, so an agent can tell which tool to pick.

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: prefer appinsights_diagnose_slowness for a ready-made slowdown report, use this tool for more specific/custom queries. It also names the prerequisite (configured connection via appinsights_set_connection or env vars) and includes trigger phrases.

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

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

The description goes well beyond annotations by disclosing that the client secret is AES-256-GCM encrypted in memory, never written to disk, never echoed back, and that only read-only permissions are needed/used. It also explains session-scoped lifetime and automatic reuse behavior. No contradiction with annotations was found.

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 detailed but well-structured, with the core behavior front-loaded and the credential-procurement guidance separated into a clearly labeled section. Every sentence adds useful information, including the locked-server caveat that directly affects whether the agent should attempt this call.

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 session-configuration tool, the description covers the critical setup, reuse, expiry, clearing, and locked-server behavior, along with detailed credential guidance. The only minor gap is that it does not describe the success/error response shape, but with no output schema and a semantically simple setter operation, this is a low-risk omission.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description adds meaningful real-world guidance for sourcing workspaceId and the Entra ID parameters, including the critical distinction between workspace ID and App Insights app ID, plus required roles. However, ttlMinutes receives no extra description-level guidance beyond the schema.

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

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

The description states a specific verb ('register') and resource ('the D365 F&O environment's Application Insights / Log Analytics connection') and further scopes it to the 'CURRENT session'. It also distinguishes itself from siblings by noting that appinsights_query and appinsights_diagnose_slowness use this connection automatically and that appinsights_clear_connection removes 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 explicitly explains when to use the tool: before querying or diagnosing via Application Insights, and that it remains active until expiry or explicit clearing. It also documents the locked-server deployment scenario where the tool is disabled and server credentials are used instead, which is a clear exclusion/alternative condition.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond annotations: parallel execution, maximum 6 queries, and that all matching objects are FULLY loaded so no follow-up call is needed. This helps the agent understand side effects and performance characteristics.

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 usage condition and alternative. It is somewhat long due to the trigger phrase list, but that list provides practical guidance. Overall it is structured and wastes little space.

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

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

For a read-only batch search tool with fully described parameters and safety annotations, the description covers everything needed: when to use, how it behaves, constraints, and follow-up guidance. No gaps remain 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 coverage is 100%, and the schema descriptions are already clear about newline-separated queries, max 6, topK and topObjects meaning. The description reinforces the 'each line becomes one parallel search' idea but does not significantly add 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?

The description states a specific verb and resource: runs multiple D365 searches in parallel, equivalent to search_d365_code. It explicitly differentiates itself from the sibling search_d365_code by covering the batch case, 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?

The description opens with a WHEN condition and explicitly says to use it INSTEAD of multiple sequential search_d365_code calls. It also provides a list of trigger phrases and warns not to follow up with get_object_details, which gives clear selection and exclusion criteria.

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, idempotentHint=true, and destructiveHint=false; description adds the comparison scope but does not disclose return shape or failure behavior. With safety covered by annotations, 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?

Two focused sentences that front-load the action and detail, with a usage cue in the second sentence; no wasted words.

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

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

Enough for a simple read-only two-parameter tool: schema covers parameters and annotations cover safety. The only gap is no explicit statement of output/return value, since no output schema exists.

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

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

Schema covers both parameters fully (100%) with examples; description reinforces comparison semantics but adds no syntax or additional parameter-specific guidance, so 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 names a specific verb ('Compare'), resource ('two D365 F&O objects'), and comparison dimensions ('fields, methods, signatures'), which clearly separates it from single-object lookup tools like get_object_details and version diff 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?

States two concrete use cases ('standard vs customisation', 'two similar tables'), telling an agent when the tool is appropriate, though it does not explicitly name alternatives or exclusions.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), it explicitly states 'never writes to the filesystem, never mutates external state, and is safe to expose from the cloud MCP' and clarifies that disk writing is the client's job. This fully discloses the tool's side-effect boundary and is consistent with 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 very long, but the length is justified by about 20 AOT types with distinct option sets. It is front-loaded with purpose and safety, then organized by type with consistent formatting; minor formatting inconsistencies and overall bulk keep it from a perfect score.

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 having no output schema, it states the return value ('XML + the correct file path') and the caller's follow-up action. Combined with exhaustive parameter documentation and side-effect disclosure, nothing critical is missing for an agent to invoke the tool correctly.

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

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

The schema only defines a generic options dictionary, but the description documents every aotType-specific option with syntax, defaults, enums, CSV layouts, and examples. This is far beyond what the input schema provides and is essential for correctly invoking the tool.

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

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

Opens with a specific verb and resource: 'Generate a complete, ready-to-deploy D365 F&O AOT XML scaffold for any object type.' It also states the two outputs (XML + file path) and the caller's write responsibility, making the tool's scope unambiguous and distinct from code-generation siblings like generate_xpp_form or generate_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 gives clear context: it is for producing AOT XML scaffolds, is server-side read-only, and the client is responsible for persisting output. It does not explicitly name sibling tools to use instead for other generation tasks, so it stops short of a full when/when-not statement.

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 convey idempotency and non-destructiveness, and the description adds useful context by specifying that the removal is scoped to the current session and targets the cache created by d365fo_set_connection. This goes beyond the structural 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?

A single sentence that names the action, the resource, the scope, and the originating tool. There is no redundancy or filler, and the essential information is front-loaded.

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

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

For a zero-parameter, session-state-clearing tool with a clear relation to d365fo_set_connection, the description fully covers what an agent needs to know. No output schema is present, but none is necessary for this trivial no-input operation.

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

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

The tool has zero parameters, so there is no parameter meaning to add. The description correctly confirms that the action operates on session state rather than requiring any input, which is sufficient.

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 ('removes') and a specific resource ('D365 F&O connection cached for the current session'), and it references the paired tool d365fo_set_connection that created the connection. This makes the tool's function unambiguous and clearly distinguishable from its sibling set_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?

The description clearly implies this is used after d365fo_set_connection to clear the connection for the current session. It does not explicitly list when not to use it or name alternatives, but the pairing with d365fo_set_connection gives sufficient context 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 annotations, the description discloses meaningful behavior: client secret encryption (AES-256-GCM), no disk persistence, no echoing back, automatic propagation to odata_* and dmf_* tools, expiration, and the clear_connection lifecycle. These details are not present in the annotations and materially affect how an agent should treat credential state.

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

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

The description is front-loaded with the core purpose, and every following sentence contributes non-obvious context: security guarantees, propagation behavior, recommendation, and locked-deployment exception. There is no filler or repetition of schema 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?

For a session-level connection setter, the description covers what the tool does, how the secret is handled, how long the connection lasts, how it is cleared, and when it must not be invoked. With the schema fully documenting parameters, no critical call-time information is missing even 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 description coverage is 100%, so the schema already documents all five parameters (baseUrl, tenantId, clientId, clientSecret, ttlMinutes). The description adds only high-level context ('URL + Entra app-registration credentials') rather than new per-parameter semantics, matching the baseline for complete 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 uses a specific verb ('register') and identifies the exact resource ('D365 F&O connection') with a clear session scope. It also distinguishes itself from sibling connection tools by naming d365fo_clear_connection 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?

It explicitly says 'Use this instead of resending the secret on every call,' giving a concrete when-to-use recommendation. It also covers the key exclusion: in locked server deployments (D365FO_LOCK_SERVER_CONFIG=true) the tool is disabled and server credentials are used instead, steering agents away from a broken call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the return format ('compact issue table with line + fix') and a meaningful environmental prerequisite. The phrase 'Auto-fixing' introduces slight ambiguity about whether this tool mutates code, but it does not directly contradict the annotations.

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

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

Three sentences with zero redundancy: the first defines scope and issue types, the second states the output, and the third provides usage guidance and a prerequisite. Information is front-loaded and 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?

With no output schema, the description responsibly states the return value as an issue table with line and fix. It also covers when to use the tool and a key environment prerequisite. The only gap is that it does not clarify whether 'Auto-fixing' is an action this tool performs or an external follow-up, but the core context for calling and interpreting results 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%, so the schema already documents objectName and methodName adequately. The description reinforces the object-level scope ('Profile an X++ object') but adds no extra parameter semantics beyond the schema. Baseline 3 is appropriate when the schema carries the load.

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 'Profile' plus resource 'X++ object' and enumerates exact performance issue patterns (N+1, queries in loops, missing field lists, row-by-row, missing firstOnly). The description also distinguishes this from validate_best_practices, making 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?

Explicitly says 'Only call when performance is explicitly the concern' and directs to validate_best_practices for general quality. It also discloses the D365_CUSTOM_MODEL_PATH prerequisite for auto-fixing, giving an agent clear context on when to invoke and what conditions apply.

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 description need not repeat them. It adds the useful behavioral detail that a baseline must be saved before comparing, implying persistent local state. The save_baseline action's local file write does not contradict the readOnlyHint annotation since it does not mutate the external D365 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 purpose statement is front-loaded, and the usage guideline follows immediately. Every word contributes 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?

The description covers the primary workflow but fails to mention the 'compare_caches' action, so an agent reading only the description would not know that direct cache-to-cache comparison is possible. It does not describe the changelog return format beyond naming the categories, though no output schema exists. Overall moderately complete but with a clear gap.

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

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

Schema description coverage is 100%, so each parameter is already documented per action. The description adds a temporal relationship between parameters (save baseline first) but no additional parameter syntax or format details, so 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 uses a specific verb ('Compare') and resource ('two D365 F&O KB snapshots') and names the output ('changelog with added/removed/modified objects'). This clearly distinguishes it from sibling tools like compare_objects or list_objects, which operate on different resources or produce different outputs.

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 an explicit workflow: 'Use action save_baseline once, then compare between two snapshots,' which explains the required ordering. It does not name alternatives or exclusions, and it omits the third action (compare_caches), so it stops short of a full 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?

It discloses important behavior beyond annotations: action routing to identical implementations, per-action parameter groups, optionality markers, defaults like execute/overwrite/reExecute, and the use of executionId for status polling. It does not describe return values or failure behavior, but annotations already establish the read/write/destructive 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?

Despite covering five operations and 20 parameters, the description is well-structured and front-loaded. Each action gets one compact line listing its parameters, and the introductory sentence establishes the purpose without wasted words.

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

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

For a consolidated tool with 20 parameters, no output schema, and annotations available, this description is very complete: it covers all five operations, their dedicated-tool equivalences, and relevant defaults. The main remaining gap is that it does not describe return or status-response shapes, but the action mapping and executionId hint mitigate this.

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 each parameter. The description adds meaning by grouping parameters by action, marking optionality inline, and clarifying key relationships such as filePath OR csvContent, executionId from import/export, and operationType defaulting to 'Export'.

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

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

The opening sentence clearly states this is a consolidated entry point for all five DMF operations and explicitly lists them. It also distinguishes itself from the dedicated sibling tools by saying it forwards to the exact same implementation with identical behavior and validation.

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 action values and maps each one to its dedicated tool, so an agent knows exactly which action to select for a given operation. It notes the dedicated tools remain available unchanged, but does not explicitly state when one should prefer the consolidated tool over a dedicated one.

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

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

Goes well beyond the annotations by disclosing the internal mechanism (kernel builds the packed query, container envelope stripped at QueryRun.pack(), inner blob PATCHed onto DataManagementDefinitionGroupDetails.QueryData), the exact persisted format, the environment prerequisite, and the non-cascading side-effect on child rows. No contradiction with annotations: idempotentHint=true aligns with filter reapplication, destructiveHint=false aligns with the scoped, non-cascading change.

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 in sentence one, and each subsequent clause carries decision-relevant content: scope limit, wildcard behavior, parent/child caveat, and prerequisite. The mid-section kernel/container/PATCH detail is dense jargon but earns its place by explaining why the persisted format matches DMFDefinitionGroupEntity; it is only slightly heavier than strictly 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?

For a tool with deep D365 FO internals, 5 required parameters, and no output schema, the description thoroughly covers scope, constraints, side-effect boundaries, and prerequisites. The remaining gaps: it does not state whether reapplying the tool with a different value on the same row replaces or merges the existing filter, nor describe the success/completion signal.

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, but the description adds real semantic nuance: it explains the per-call constraint ('single field = single value per call'), explicitly states wildcard pass-through ('1001*'), and provides additional entityRowName examples ('Vendor bank accounts', 'Vendor postal addresses') that clarify how to use the parameter beyond the schema's single example.

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

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

The first sentence names a specific verb ('Apply'), resource ('ONE entity row of an existing DMF project'), and outcome ('export only contains the matching records'). It distinguishes itself from sibling DMF tools (dmf_create_data_project, dmf_export_package, dmf_get_job_status) by scoping to filtering an existing project row, and explicitly states the single-field/single-value limit.

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

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

Provides clear usage context: call once per entity row, wildcards pass through, and the critical caveat that filtering a parent does NOT auto-filter child rows, so the same filter must be applied to related rows. It also states the environment prerequisite ('GenerateQueryData' action). However, it never explicitly names sibling alternatives or says 'use this instead of X', so when-not guidance is scenario-based rather than tool-comparative.

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 discloses the concrete side effects beyond what the annotations provide: it POSTs to DataManagementDefinitionGroups and DataManagementDefinitionGroupDetails with AutoGenerateMapping=Yes, revealing exactly which OData endpoints are touched and that FO auto-generates mappings. It also elaborates the idempotency annotation by explaining the practical meaning (existing project reused, entities present are skipped). No contradiction exists between the description and 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?

All five sentences earn their place: purpose, mechanism, idempotency, workflow routing, and parameter guidance each carry distinct value. The purpose is front-loaded in the first sentence. It is on the longer side, but the tool is complex (4 parameters, domain-specific DMF concepts, several siblings) and every clause contributes, 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?

The description covers the key prerequisites (existing source data format, no X++ customization) and the post-condition workflow for exports. With no output schema, a brief note on what the tool returns would strengthen it, and the import path's next step (dmf_import_file exists among siblings) is not mentioned. These are minor gaps against an otherwise dense and sufficient description for a 4-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?

With 100% schema coverage, the baseline is 3, but the description adds meaningful guidance beyond the schema: it warns that sourceName must reference an EXISTING format and gives a concrete example ('comma-delimited format'). It also explains why entities is a comma-separated string by describing the underlying per-entity row creation, and it contextualizes operationType by noting EXPORT projects are later run by dmf_export_package.

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-plus-resource ('Create (or extend) a DMF data project') and immediately disambiguates the operation modes (EXPORT or IMPORT). It distinguishes itself from the sibling dmf_export_package by clarifying that this tool only builds the project while running it is a separate step. The naming convention also differentiates it clearly from dmf_apply_entity_filter and dmf_import_file.

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 workflow guidance: 'For EXPORT, the project can then be run with dmf_export_package,' which tells the agent this tool is a setup step and points to the correct sibling for execution. It also states the idempotent reuse behavior, which informs when calling it again is safe. However, it does not explicitly contrast with dmf_import_file or address when a user would need custom X++ mapping instead.

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

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

Annotations indicate mutation (readOnlyHint=false), idempotency, and non-destructive behavior; description adds meaningful context: it is a trigger operation, it waits until completion to return a URL, and it requires a preconfigured project. It does not explicitly detail polling/timeout behavior, but the schema parameter and 'when complete' phrase cover the essential trait.

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 with no wasted words: action/result, critical prerequisite with a creation fallback, and the ad-hoc alternative. The prerequisite warning is placed immediately after the main action where it matters.

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

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

For a tool with no output schema, the description states the return value and key precondition, and routes to the correct sibling. The only notable gap is lack of detail about the polling behavior or failure outcome, but pollTimeoutSeconds in schema plus 'when complete' make the tool callable.

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 five parameters. The description only reinforces definitionGroupId's requirement ('must already exist') without adding new semantic detail about legalEntity, reExecute, packageName, or pollTimeoutSeconds, so 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 opens with the concrete action ('Trigger a bulk export through the Data Management package REST API') and names the deliverable ('return the download URL when complete'). It further differentiates from siblings by pointing to odata_export_entity for ad-hoc exports and dmf_create_data_project for creating the prerequisite project.

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 states when the tool applies (bulk export through an existing DMF project) and gives two routing rules: create the missing project with dmf_create_data_project, or use odata_export_entity for ad-hoc exports. This is clearer than most sibling descriptions.

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, idempotentHint, and non-destructive behavior. The description adds value beyond annotations by disclosing that the tool is a poller, enumerating possible statuses, and noting that a completed export returns a download URL. 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?

Two sentences with no filler. The core action and target are front-loaded, the status examples are compactly placed in parentheses, and the download-URL detail is a single meaningful addition.

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

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

For a one-parameter, read-only, idempotent polling tool with no output schema, the description gives an agent everything essential: how to identify the job, what statuses to expect, and what extra result appears for completed exports. 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?

The input schema already fully documents executionId, including that it is required and returned by dmf_import_file or dmf_export_package, with 100% schema description coverage. The tool description reinforces 'by its executionId' but does not add new parameter semantics, 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 target resource ('status of a DMF import/export execution'), keyed by executionId. It also lists concrete status values and mentions the download-URL behavior for completed exports, making it clearly distinguishable from dmf_import_file, dmf_export_package, and other 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 establishes a clear usage context: it is the follow-up polling operation after an import/export is started, and the schema's executionId description explicitly points to dmf_import_file or dmf_export_package as the source. It does not explicitly list exclusions or alternatives, but the intended workflow is obvious.

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?

Adds substantial context beyond the annotations: the in-memory package build, Azure blob upload, ImportFromPackage call, the auto-creation of the data project, batch execution with polling, and an error-keys file URL on row failures. The destructiveHint and non-idempotent annotations are consistent with the described overwrite-and-import behavior, so there is no contradiction.

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

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

Four sentences arranged as purpose, mechanism, execution behavior, then usage requirements — front-loaded and logically ordered with no filler. For a tool this complex, each 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?

Since no output schema exists, the description correctly covers return values (final status and error-keys file URL) plus the full execution flow. Minor gaps: 'polls until completion' overlooks the pollTimeoutSeconds early-return behavior, and the stage-only mode (execute=false) appears only in the schema — both are documented there, limiting practical impact.

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, but the description adds genuine semantic value by tying entityName to a resolution workflow ('Resolve the entity name from the KB (find_entity_for_table) -- do not invent it'), which the schema's example does not convey. The filePath/csvContent exclusivity is useful reinforcement even though both parameter descriptions already state 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 first sentence states a specific verb and resource — 'Bulk-import a CSV file into a D365 F&O entity through the Data Management package REST API' — and the AUTO-CREATES clause explicitly distinguishes it from sibling dmf_create_data_project. The import direction separates it from dmf_export_package and odata_export_entity, so an agent can pick it 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?

Provides clear usage context: the caller must supply either filePath or csvContent, and it instructs the agent to resolve entityName via find_entity_for_table ('do not invent it'), naming the right sibling for the prerequisite step. It stops short of explicit when-not-to-use guidance against alternatives such as odata_upsert_rows for non-bulk loads.

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

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

Beyond the annotations (idempotent, non-read-only, non-destructive), the description discloses that no FO credentials are needed, that autoGeneratedFields are stripped from the output 'so FO generates them', and that base64 upload is limited to small files. It also exposes the CSV-vs-JSON output differentiation and the listSheetsOnly diagnostic mode. No statement contradicts the annotations, and the idempotentHint=true aligns with the offline pure-transform 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?

The description is front-loaded with the core purpose and the key differentiator (offline transform, no credentials), and nearly every sentence carries load-bearing information with zero fluff. However, the mapping spec details are crammed into a single dense sentence with mixed bracket notation, and breaking the content into short bullets or lines would improve parseability without adding bulk.

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 input source constraints ('one of', 'small files only'), the mapping spec shape, output routing, and diagnostic mode — nearly everything an agent needs to invoke it correctly. Minor gaps remain, such as the exact shape of the listSheetsOnly response and failure behavior when none of the three input sources is provided.

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, but the description adds substantial meaning the schema lacks: the full mappingJson spec structure (conditionalValues with {sourceColumn,matches[],values{}}, staticValues, deduplicateOn, autoGeneratedFields as array or sheet-keyed object with a concrete example) and the semantic consequence that those fields get removed. It also enriches the format parameter by mapping it to downstream consumers (dmf_import_file vs odata_upsert_rows), which the bare 'csv or json' schema text does not provide.

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

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

The opening sentence names a specific action (transform), resource (multi-sheet .xlsx), mechanism (data-driven JSON mapping), and outcome (DMF-ready rows). It anchors the tool as the offline equivalent of FO_TransformExcelForDMF, and the output-routing sentences ('feed to dmf_import_file' / 'feed to odata_upsert_rows') keep it clearly distinct from the import/upsert siblings in the same DMF family.

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 tells the agent exactly what to do with the result — CSV goes to dmf_import_file, JSON goes to odata_upsert_rows — and states when the tool applies ('NO FO credentials required (offline transform)'). It also explains the diagnostic mode (listSheetsOnly=true) and the 'one of three inputs' constraint. It never explicitly names a when-not-to-use alternative, but the pipeline routing effectively positions it against its siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by stating the output is 'plain business language' with 'no X++ or workflow engine jargon,' which helps an agent set user expectations beyond what annotations 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 front-loaded with the WHEN clause and trigger examples, making it easy for an agent to quickly match intent. It is slightly repetitive with the 'WORKFLOW EXPLAINER' header and the following explanation, but every section still contributes useful guidance.

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

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

For a low-complexity tool with one documented parameter and annotations covering safety, the description is complete: it specifies when to use it, what it explains, the output style, and the alternative for technical details. No critical information 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 schema covers the single parameter objectName fully with example values such as 'SalesTable' and 'PurchTable', so the baseline is 3. The description does not add additional parameter-specific semantics beyond indicating the object is a workflow-related D365 object, which the schema already implies.

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 verb and resource: it 'Explains a D365 approval workflow: who approves, what states exist, and what happens on approval or rejection.' It distinguishes itself from get_object_details by explicitly saying it is NOT for 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?

The description provides an explicit WHEN section with concrete user phrasings such as 'explain the workflow for' and 'what happens when a user submits.' It also names get_object_details as the alternative for technical workflow class details, giving clear 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 mark this as read-only and non-destructive. The description adds genuinely useful behavioral context: parallel fan-out, RRF merging, configured peers via environment variable, and the local server always being included as primary. This goes beyond what the 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 front-loaded with the core operation and stays efficient. Each sentence earns its place: what it does, when to use it, how peers are configured, and the local server's role. The example in parentheses is helpful without bloating the text.

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, this covers the essential operational details: purpose, configuration, merge behavior, and primary source. There is no output schema, but 'merge results' implies the return shape. It is complete enough for an agent to decide when to invoke it.

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

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

Schema description coverage is 100%, so all three parameters are already documented: query, topK, and peerApiKeys. The description adds no additional parameter-level details, but no compensation is needed since the schema carries the full semantic load.

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 ('fan-out search') and names the exact resource ('multiple ALM XPP MCP server instances') plus the merge technique (Reciprocal Rank Fusion). This clearly differentiates it from single-server search tools like search_d365_code by establishing the multi-server, federated scope.

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 use it: 'when D365 code is split across multiple organisations or knowledge bases.' It does not name an alternative tool or say 'use X for single-server search,' but the condition is clear and the exclusion is easy to infer.

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

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

Annotations already declare the operation read-only and idempotent, so the description does not need to repeat safety. It adds valuable behavioral context beyond annotations: the dependency on xref_index.json.gz (with generation command) and the vector-search fallback when the index is not loaded. This tells the agent about data availability and degraded behavior in a way the schema and annotations do not.

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

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

Two sentences carry all essential information with no filler: the first defines the tool's scope and output categories, the second states the prerequisite and fallback behavior. Information is front-loaded, with the most important purpose statement first.

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 cross-reference tool with annotations covering safety, the description is mostly complete: it names the target, the output categories, the prerequisite index, and the fallback. There is no output schema, so some ambiguity about the exact result structure remains, but the description provides enough context for an agent to decide whether and how to invoke it.

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

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

Schema description coverage is 100%, so the schema already documents methodKey format, depth bounds, categories, and maxResults. The description's list of categories (callers, callees, inheritance, etc.) loosely maps to the categories parameter, but it does not add substantive semantic 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?

The description clearly identifies the resource (a class or method) and the verb (build a full cross-reference profile), and enumerates the content: callers, callees, inheritance chain, interface implementations, overrides, attributes. It is distinguishable from siblings like find_references by this explicit scope, though it never names a sibling or states the comparison directly.

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 important context about when the tool can be used: it requires xref_index.json.gz and falls back to vector-search when XRef is not loaded. However, it does not explicitly state when to prefer this tool over sibling tools such as find_references or find_change_impact, nor does it provide exclusions or 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 annotations already declare the operation read-only and idempotent; the description adds meaningful behavioral context: it requires the XRef index, uses BFS up to 3 hops, and reports custom model extensions, interface propagation, and severity classifications. 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?

The description is dense but well-organized: WHEN, output contents, prerequisite, trigger phrases, and examples are presented in a logical order. The trigger list is somewhat redundant with the opening WHEN but still supports intent matching across languages.

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 two parameters, no output schema, and strong annotations, the description is complete enough for selection and invocation. It explains the report contents, severity classes, BFS hop limit, prerequisite XRef index, and concrete examples, leaving no major gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by showing how objectName='SalesLine' means table/class-level impact while objectName='SalesLine.insert' means method-level impact. It also ties maxDepth to BFS hop behavior, though it does not add new syntax details beyond the schema.

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

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

The description clearly states what the tool does: it assesses the blast radius of modifying an X++ object or method and returns a report with direct callers, transitive dependents, extensions, interface propagation, and severity. This differentiates it from siblings like find_callers and find_references by emphasizing impact analysis and severity classification.

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 an explicit WHEN condition ('about to modify an X++ object or method'), concrete trigger phrases, and a worked example for both object-level and method-level analysis. It does not explicitly say when to prefer simpler sibling tools such as find_callers or find_references, so it lacks a full when-not/alternatives matrix.

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 discloses the scanning behavior ('Scans all indexed AxDataEntityView objects') and the conditional generation side effect ('generateIfMissing=true to auto-generate an AxDataEntityView XML template'). Since readOnlyHint, idempotentHint, and destructiveHint annotations already cover the safety profile, this adds useful behavioral context without contradiction.

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

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

The description is front-loaded with WHEN and the core find purpose, and the structure is organized. However, it is somewhat long and repeats the generateIfMissing guidance in the opening and closing sentences; the trigger list is extensive and 'Essential for integration development' adds little 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?

Despite having no output schema, the description enumerates the returned fields and explains the search mechanism and the conditional template generation. It leaves minor gaps, such as explicit behavior when no entity is found and generateIfMissing=false, but overall it is complete for a read-only lookup tool with schema-documented 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?

The input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds operational context for generateIfMissing ('auto-generate ... when no public entity is found') but does not add meaning beyond what the schema already provides for tableName or maxResults.

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: 'Find D365 F&O data entities that expose a given table for OData/DMF integrations,' and specifies the returned fields: entity name, public entity name, IsPublic status, key fields, and data sources. It also distinguishes the find-by-table use case from sibling creation/inspection tools by adding the optional generateIfMissing behavior.

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 explicit WHEN guidance: 'developer needs to integrate via OData and wants to find the entity name for a given table,' and provides trigger phrases and an example question. It does not explicitly name alternative tools or list when-not-to-use, but the context is clear enough to route an agent 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral detail beyond that: it matches against a built-in error database, extracts D365 label IDs, searches the indexed codebase, returns root causes and resolutions, and distinguishes plain-language business explanations from developer-grade outputs. No contradiction with annotations exists.

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

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

The description is long but information-dense: the WHEN clause is front-loaded, trigger examples are compactly listed, and the [~] routing notes are separated. Every segment contributes operational guidance, so the length is justified 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 read-only diagnostic tool with no output schema, the description is remarkably complete. It states inputs, audience modes, known error categories, label-resolution behavior, best-practice moniker handling, and the return contents (root causes, step-by-step resolution, label matches, and source code locations). 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 coverage is 100%, so the schema already documents both parameters. The description adds real semantic value by explaining audienceType's developer/business split and associating errorOrSymptom with concrete triggering examples ('update conflict', 'number sequence not set up'), which helps the agent formulate valid input.

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

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

The description names a specific verb and resource: 'Find known D365 F&O error patterns matching an error message or symptoms description.' It details what the tool does beyond simple search — resolving label IDs, searching the codebase, and returning root causes — and is clearly distinct from sibling tools like search_d365_code and search_labels.

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 opens with WHEN it should be used, provides concrete developer and business trigger phrases, and gives routing guidance: call search_labels first for '@SYS' label IDs, and use run_best_practices_check_scoped for deciding whether an object breaks a BP rule. This leaves no ambiguity about when to choose this tool over 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 description discloses that the tool searches the knowledge base for specific attribute patterns, which signals the underlying mechanism and potential limitation (static pattern matching rather than runtime inspection). Annotations already cover read-only and non-destructive behavior, so the description adds useful method context beyond those.

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 efficiently structured with the core action first, followed by pattern details, filter usage, and WHEN examples. The WHEN list includes redundant language variants, but the space is justified by the multilingual user base.

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 required parameter, the description covers purpose, search method, optional filters, and common query intents. There is no output schema, but the expected result (event handlers) is implied clearly enough for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds a concrete event example and clarifies objectName refers to a table or class name, but this is marginal 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 clearly states the tool finds event handlers that subscribe to events on a D365 table or class, naming the exact attribute patterns searched. This distinguishes it from broader sibling tools like find_references or find_callers by focusing specifically on SubscribesTo handlers.

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 guidance with concrete query intents and example phrases, including non-English variants. It does not explicitly state when to use an alternative tool, but the intent list is specific enough to guide 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 cover read-only, idempotent, and non-destructive behavior; description adds that it queries Azure DevOps Code Search in real-time and may include extensions not yet in the KB. This is useful behavioral context beyond the schema.

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

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

Two sentences pack the purpose, coverage, and usage mandate without fluff. The most important guidance is front-loaded.

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

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

For a one-parameter search tool with no output schema, it explains what is searched, why it matters, and the real-time KB fallback. It does not detail output or failure modes, but those are not critical with this simple contract.

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

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

The single baseObjectName parameter is fully described in the schema with examples, so schema coverage is high. The description adds no additional parameter-level semantics beyond calling it the base object.

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

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

Clearly states it finds all extension objects, CoC classes, and event handlers for a base object, distinguishing its broad discovery role. The explicit reference to specific artifact types makes 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?

Explicitly directs ALWAYS calling before creating a new extension to avoid parallel customizations, providing a strong usage cue. It does not explicitly name alternative sibling tools or 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 readOnly/idempotent/non-destructive; the description adds non-obvious runtime behavior: an O(1M+ chunks) expense warning, dual-form label ID expansion (`@SYS124480` and `@SYS:124480`), and the extension-handler exclusion. All fully consistent with the annotations — no contradiction.

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

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

Six compact sentences with the core action and use case front-loaded, followed by the cost warning, alternatives, and exclusions. Every sentence earns its place; no repetition of schema or annotation info.

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?

Although there is no output schema, the schema's maxResults ('Maximum referencing objects to return') and locationsPerObject ('call sites... per referencing object') already convey the result shape. The description covers purpose, usage timing, cost, alternatives, special label handling, and exclusions — an agent has everything needed 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 coverage is 100%, so baseline is 3. The description still adds meaning by broadening the name parameter domain beyond the schema's 'object or method name' to include fields and label IDs, and by documenting the label ID format expansion. maxResults and locationsPerObject are already well described 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?

Opens with 'Full index scan for all usages of an object, method, field, or label ID' — a specific verb, resource, and scope. The label-ID and not-for-extensions clauses directly distinguish it from siblings find_callers and find_extensions, so an agent can disambiguate 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?

Explicitly states the trigger ('Use for impact analysis before changing or deleting an object'), the cost-based alternative ('Prefer find_callers when XRef index is loaded (O(1))'), and a hard exclusion ('NOT for extensions only — use find_extensions for CoC/event handlers'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so no restatement is needed. The description adds useful non-obvious behavior: conditional delegation to get_relation_graph with O(1) performance when the relation index is loaded, plus a warning against redundant calls. It does not detail the exact result record shape, but for a read-only lookup 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?

Three sentences each earn their place: one defines results, one defines call timing, and one defines the relationship to a sibling tool. There is no filler, repetition, or vague framing.

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

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

For a single-parameter, read-only lookup, the description is complete enough: it states what is returned, when to call it, and how to avoid duplicating work with get_relation_graph. No output schema exists, but the return contents are summarized at an adequate level for an agent to invoke the tool correctly.

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

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

The input schema has 100% description coverage for objectName, including examples, so the baseline is 3. The description clarifies what the tool does with the object name but adds no new constraints, formatting, or semantic details for the parameter 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 names a specific operation—returns ALL FK/DeleteAction/DataSource relations—and explicitly covers both outgoing relations and incoming back-references. It is clearly distinguishable from related tools such as get_relation_graph by describing both the scope and direction of results.

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 trigger: 'Call BEFORE generating multi-object code' to understand the dependency graph. It also names get_relation_graph as an internal delegation target and warns 'do NOT call both tools for the same object', which prevents duplicate work.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses non-obvious behavior: it walks a pre-computed relation graph in both directions, uses BFS with O(1)-per-node cost, returns only names and relation kinds to save tokens, and enumerates the included edge types. This is exactly the kind of behavioral context agents benefit from.

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: trigger condition, triggers, algorithm behavior, output token-lightness, and sibling comparison. Every sentence serves a clear purpose, and the key usage condition is front-loaded. The length is justified by the need to disambiguate from closely related tools.

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 multi-hop traversal tool with no output schema, the description is complete: it defines the input semantics with examples, describes the output shape as a chain of object names and edge kinds, and provides performance context. Error cases like unreachable nodes are not mentioned, but that's a minor omission given the strong annotation and schema coverage.

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 documents all four parameters with descriptions, defaults, and max values (100% coverage), so the description doesn't need to add much. It does not clarify parameter semantics beyond the schema, which is acceptable under the baseline for full schema coverage.

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

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

The description states a specific verb and resource: find how two AOT objects are connected via the chain of relations linking them. It explicitly contrasts with `get_relation_graph`, making the tool's unique role unmistakable. The trigger phrases further reinforce the intended 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?

It opens with 'WHEN: you need to know HOW two AOT objects are connected' and lists concrete trigger examples in English and French. It explicitly tells the agent to use `get_relation_graph` for a single object's full neighbourhood, leaving no ambiguity about when to select this tool instead.

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 cover the read-only, idempotent, non-destructive safety profile. The description adds useful behavioral context by defining what 'structurally similar' means (same kind, similar method set, similar field set), which goes beyond the tool name and helps an agent predict behavior.

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

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

Two concise sentences: the first states the core behavior and similarity criteria, the second states the primary use case. Every word earns its place with no fluff or repetition of schema 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?

The description is adequate for a read-only, list-returning tool with annotations covering safety and a self-explanatory schema. It does not describe the return format (e.g., list of object names), but given the tool name and 'find ... objects' wording, an agent can infer the output shape. Minor gap: no explicit mention of result ordering or default scoping.

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 three parameters. The description does not add parameter-level detail beyond what the schema provides, which is acceptable under the baseline of 3.

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

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

The description clearly identifies the verb (Find), the resource (D365 objects), and the distinguishing behavior (structurally similar, same kind, similar method set, similar field set). This differentiates it from sibling search/find tools like search_d365_code or find_references, which are text- or reference-based.

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 when-to-use trigger: 'when you need a working reference implementation to copy from.' It does not explicitly name alternative tools or state when not to use it, but the use case is specific enough to guide an agent.

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

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

Beyond the readOnly/idempotent/destructive hints, it discloses the optional external Ollama dependency, the OLLAMA_HOST requirement, the ALMXPP_SUMMARIZE_MODEL usage, and the fallback to built-in suggestions when Ollama is unavailable. This gives the agent an accurate model of runtime behavior and side effects.

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 key WHEN condition, then states the return value, then covers triggers and optional behavior. Every sentence adds practical information with 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?

With no output schema, the description usefully summarizes what the tool returns: built-in fix suggestions plus optional AI patches. It also covers the external prerequisite and fallback. It could be slightly more explicit about how maxViolations shapes the output, but the description is adequate 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. The description adds useful reinforcement that generatePatches=true triggers Ollama calls, but otherwise offers no new parameter-level semantics 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 clearly states what the tool does: returns BP violations with built-in fix suggestions and optionally AI-generated X++ code patches. It explicitly ties itself to validate_best_practices, distinguishing its role as the follow-up fix suggestion step.

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

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

Provides an explicit WHEN: use it when validate_best_practices returned violations. Trigger phrases are included, and the Ollama prerequisite/fallback is described. However, it does not explicitly say when not to use it versus related tools like suggest_refactoring.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by stating it produces complete AxDataEntityView XML with data sources, field mappings, entity key, OData public naming, and a staging table template, and that it uses real field names and relations from the local custom model. This clarifies the read-only, generative nature of the tool beyond the annotations.

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

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

The description is well-structured with a 'WHEN' label, a trigger list, output details, and a clearly highlighted always-do instruction. It is longer than average due to the trigger phrases, but those phrases serve a real purpose for agent intent matching and are organized into a discrete section rather than buried in 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 there is no output schema, the description does a good job explaining what the tool produces: complete AxDataEntityView AOT XML with data sources, field mappings, entity key, OData settings, and staging table template. It also communicates essential context about using the local custom model and the prerequisite call to find_entity_for_table. It could be more explicit about how the XML is returned (e.g., string vs. file), but the core information needed to invoke and interpret the tool 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%, so the schema already documents all six parameters. The description adds some context by linking parameters to outputs — e.g., field mappings, IsPublic/PublicEntityName for OData, and join/data source behavior — but it does not add per-parameter details beyond what the schema provides. Score 3 is the appropriate baseline for full schema coverage.

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

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

The description states a highly specific action — CREATE/generate a data entity (AxDataEntityView) AOT XML from a table — and clarifies the intended use cases: OData, DMF, and data migration. It includes a broad set of trigger phrases that make intent matching robust, and the mention of AxDataEntityView clearly distinguishes it from generic AOT creation tools like create_aot_object.

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 ('developer needs to CREATE a data entity...'), provides trigger examples, and gives a mandatory precondition: 'ALWAYS call find_entity_for_table first to verify a standard entity doesn't already exist.' This effectively defines when not to generate a new entity and names the sibling tool to consult first.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered and the description does not contradict it. The description adds context beyond annotations: output is Mermaid diagrams that render directly in Copilot Chat, Cursor, Claude, and markdown viewers, and it explains why 'flow' is intentionally disabled (static call trees are misleading due to CoC and event handlers). This is meaningful behavioral context, though it doesn't discuss failure modes or edge cases.

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 on the longer side but front-loads the WHEN clause and triggers, and every subsequent section is functional: rendering environments, per-type semantics, sibling routing, and the disabled-mode rationale. The nine-trigger list is mildly redundant (several are near-synonyms), but it supports reliable surface-form matching for an agent.

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 correctly carries the burden of explaining outputs — Mermaid diagrams and their rendering environments. It covers both active modes, the disabled mode with a reason, parameter intent, and the key sibling alternative. The only minor gap is that it doesn't distinguish the 'er' mode from the sibling get_relation_graph, which could overlap in scope.

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 beyond the schema by expanding diagramType semantics — spelling out the security chain structure (Role->Duty->Privilege->EntryPoints) and the ER scope ('a table and its relations'). It also explains why methodName is inert in practice ('Not used — flow diagrams are disabled'), which the schema states only tersely.

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 precise verb+resource construction — 'Generate visual Mermaid diagrams from D365 F&O knowledge base data' — and enumerates the two active diagram types ('er' for entity-relationships, 'security' for Role->Duty->Privilege->EntryPoints chains) plus the disabled 'flow' type. It explicitly differentiates itself from the sibling trace_security_chain by framing that tool as the structured-text alternative, so an agent can reliably distinguish them.

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

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

The description opens with an explicit WHEN clause and lists nine concrete trigger phrases ('generate diagram', 'diagramme', 'visualize', 'ER diagram', etc.). It states the exact selection condition for the alternative tool — 'for the structured text chain with tables of duties/privileges/entry-points use trace_security_chain instead' — and explicitly disables 'flow' with a rationale. This is exemplary routing guidance that leaves nothing to inference.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds useful behavioral context by listing the exact sections produced (Purpose, Business Context, Data Fields, Business Rules, Related Objects, Security, Open Questions). It clearly signals that the tool composes a document rather than modifying system state.

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 organized with WHEN, function statement, generated sections, and triggers. It is slightly redundant because trigger phrases in the WHEN line overlap with the Triggers list, but it is still compact, scannable, and every section adds useful information.

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

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

For a 3-parameter tool with no output schema, the description covers the main requirements: what it generates, when to use it, when not to use it, and the trigger phrases. It does not explicitly describe the output format or return value, but 'structured FDD ready for review and sign-off' provides sufficient expectation for the agent.

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 does not add much beyond the schema for parameters, though the mention of 'with resolved labels' gives a small hint about how `objectName` affects the output. The optional `context` and `language` are already well 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 identifies a specific verb and resource: 'WHEN: user asks to write or generate a Functional Design Document' and 'Produces a structured FDD'. It also explicitly distinguishes itself from `get_object_details`, which is for developer technical docs, so an agent can select the right tool 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 provides explicit WHEN conditions, a clear NOT case, names the alternative tool (`get_object_details`), and lists concrete trigger phrases in multiple languages. This gives the agent strong, actionable guidance on when to use this tool versus siblings.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context by explaining that generated X++ is only a template, that joins depend on the relation index, and that results are returned side-by-side with explanations. 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 longer than average but well-structured with WHEN, triggers, supported features, warnings, and return value. Every section earns its place, and important usage warnings are clearly flagged.

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 explicitly states the return format: side-by-side X++ and SQL with explanations. It also covers prerequisites, supported query features, natural-language input, and the production caveat, making it sufficient for an agent to invoke correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics by explaining that natural-language descriptions trigger auto-detection of fields/joins/filters and that multi-table joins are auto-detected from relations, which clarifies the description and joinTables parameters beyond schema details.

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

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

The description states a specific action—generate both X++ select statements and equivalent T-SQL queries for D365 F&O tables—and clearly identifies the resource and output. It also distinguishes itself from related tools by referencing the prerequisite use of find_related_objects and get_relation_graph for join accuracy.

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' section and trigger phrase list tell an agent exactly when to invoke this tool. It also gives explicit guidance to call find_related_objects or get_relation_graph first for multi-table joins, and warns that generated X++ is a template requiring adaptation, which is strong usage direction.

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 idempotent and non-destructive, and the description adds meaningful behavioral context: it renders files, returns download URLs, does not invoke an LLM, and depends on prior manual analysis. This goes beyond the structured hints, though it does not describe failure modes, auth requirements, or file lifecycle details.

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

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

The description is two compact sentences with no filler. The WHEN condition is front-loaded, the action is stated directly, and the critical non-LLM caveat is placed at the end where it reinforces rather than distracts.

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 100% schema coverage and no output schema, the description provides the essential workflow context: the prerequisite call, the expected input structure origin, the two output formats, and the return type. It could go slightly further by describing what the agent should do with the returned URLs or how errors manifest, but 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 schema fully documents every parameter. The description adds a small amount of extra meaning by tying findingsJson to the instructions field from prepare_release_note_context and clarifying the relationship between v1/v2/customModelLabel and the same values passed to the context tool, but this is marginal 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 clearly states the tool's specific action: rendering a pre-analyzed findings array into downloadable Word (.docx) and PowerPoint (.pptx) release notes and returning their URLs. It distinguishes itself from the sibling prepare_release_note_context by explicitly framing this as the post-analysis rendering step and by noting it does not call any LLM itself.

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 an explicit precondition: call this only after prepare_release_note_context has been used and the agent has manually analyzed the objects array to produce findings. It also warns that the tool does no reasoning, so the agent must not expect it to fill that gap. However, it does not name alternative tools or formally state when not to use it beyond the implied precondition.

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, idempotentHint, and non-destructive behavior; the description is consistent and adds meaningful behavioral detail: per-role listing, inferred license tiers, and surfacing orphan duties/privileges. It does not describe output format or scale, but for a read-only report generator this is a reasonable disclosure level.

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 concise sentences with no filler. The purpose is front-loaded, the report contents are listed efficiently, and the orphan-detection behavior is a distinctive final sentence. Every sentence contributes information.

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