ALM X++ MCP Server

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

Annotations declare readOnlyHint=true; the description confirms this by framing the tool as analysis-only that 'Produces a ready-to-post PR review comment' while delegating the actual write operation to another tool. It adds critical context about authentication ('Requires DEVOPS_ORG_URL + DEVOPS_PAT') and explains behavior for large PRs ('Larger PRs get a summary for remaining files').

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

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

The description is information-dense and logically structured: Priority Trigger → Core Action → Detailed Steps (1-4) → Workflow Handoff → Requirements. While lengthy due to the extensive trigger list and detailed analysis steps, every sentence serves a distinct purpose for agent routing or execution.

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

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

For a complex D365 analysis tool with no output schema, the description is comprehensive. It explains the four analysis dimensions, output format ('ready-to-post PR review comment'), authentication prerequisites, and interaction patterns with sibling tools (ado_post_pr_comment), leaving no critical gaps.

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?

Input schema has 100% description coverage (e.g., 'Pull Request ID (integer), e.g. 42'), establishing a baseline of 3. The description discusses the analysis process but does not add semantic context to specific parameters beyond what the schema already 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?

Description explicitly states it 'Analyse[s] the full D365 F&O code impact of a Pull Request' and lists four specific analysis dimensions (Best Practice validation, Upgrade impact, Extension conflicts, and producing a review comment). It clearly distinguishes from sibling 'search_d365_code' with the explicit exclusion 'NEVER call search_d365_code when PR... is mentioned.'

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 exhaustive trigger phrases ('analyse PR', 'review PR', 'impact du PR', etc.) and explicit negative guidance ('NEVER call search_d365_code'). It also provides clear workflow sequencing: 'After reviewing, call `ado_post_pr_comment` to post the review (requires user confirmation).'

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?

While annotations declare readOnlyHint=true, description adds crucial behavioral context: it returns 'Raw structured context only -- NOT a finished analysis', lists 4 specific data aggregates (metadata, KB objects, custom code, CoC graph), warns about latency/token costs for images, and specifies env var prerequisites (DEVOPS_ORG_URL + DEVOPS_PAT).

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?

Lengthy but justified by complexity. Uses clear markdown headers (## WHAT THIS TOOL RETURNS, ## YOUR JOB). Minor verbosity in trigger phrase list, but every section serves a distinct purpose (scoping, invocation triggers, output contract, post-processing requirements).

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

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

No output schema exists, but description comprehensively details return structure (4 bullet points of data types). Includes prerequisite env vars, post-call processing instructions (synthesize in French, 5 required sections), and specific constraints (comment only on analyzed WI). Complete for a complex aggregation tool.

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

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

Schema coverage is 100%, providing full parameter documentation (defaults, examples, behavioral notes like 'speeds up analysis'). Description adds no additional parameter semantics beyond what the schema already provides, which is acceptable given 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?

Description opens with specific verb ('Fetch') and resource ('Work Item'), scoped to 'D365 F&O expert analysis'. Explicitly distinguishes from siblings with 'NEVER for: labels... X++ code lookup... use search_labels / search_d365_code instead'.

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 'PRIORITY TRIGGER' list with exact phrases ('analyse le workitem', '#1234', etc.) and clear exclusions ('NEVER for') naming specific alternative tools. Perfect guidance for when/when-not to invoke.

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

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

No annotations provided, so description carries full burden. It discloses auth requirements (DEVOPS_PAT with specific scopes), automatic side effects (Git branch creation, N counter increment), and state mutations (creates Task, sets relationships). Deducted one point as it doesn't mention error handling or idempotency.

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?

While well-structured with clear sections (WHEN, Triggers, Rules A/B/C, Language Rule), the description is dense and lengthy. The rules explanation is necessary but verbose; could be more scannable with formatting while retaining the critical logic.

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

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

For a complex 10-parameter mutation tool with no output schema or annotations, the description is comprehensive regarding naming logic, inheritance rules, and language handling. Minor gap: doesn't describe what the tool returns (e.g., task ID, branch name) upon success.

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 has 100% coverage (baseline 3). Description adds value by explaining workItemId semantics through the three parent relationship scenarios (A/B/C rules), and clarifies that assignTo/notifyList are embedded in the description field rather than standard ADO assignment fields.

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

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

Description explicitly states it creates a 'D365 F&O development Task work item in Azure DevOps' with specific verb (create) and resource. It distinguishes from siblings like ado_query_workitems or ado_analyze_workitem by detailing the unique naming conventions and automatic branch creation logic specific to this workflow.

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

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

Opens with explicit 'WHEN:' clause listing triggers ('create task', 'créer une tâche', 'start development on'). Details three specific scenarios (A, B, C) for when to apply different naming conventions based on parent work item relationships, providing clear contextual guidance for selection.

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

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

Annotations only declare readOnlyHint=true. Description adds substantial context: methodology details (KB signals, object count, ADO history), output format (per-phase table, confidence level, ready-to-paste format), and risk factors. Does not mention caching or performance characteristics, preventing a 5.

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

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

Well-structured with clear visual markers ([t], WHEN:, Returns:). Front-loaded with priority triggers. Slightly verbose with redundant trigger list at end repeating the WHEN clause, but every section serves a distinct purpose (sequencing vs. output format vs. trigger examples).

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 no output schema and minimal annotations, the description comprehensively compensates by detailing return values (per-phase breakdown, KB signals used, confidence level), sequencing with siblings, and paste-ready output format. Complete for a complex estimation 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%, establishing baseline 3. The description does not add parameter-specific semantics (e.g., syntax details for focusObjects or project fallback behavior) beyond what the schema already provides, but full schema coverage makes this acceptable.

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

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

Specific verb ('Estimate') + resource ('D365 F&O development effort') + scope ('hour estimate broken down by phase'). Explicitly distinguishes from sibling `ado_analyze_workitem` by stating this produces effort estimates versus 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?

Excellent explicit guidance: 'WHEN: user asks for an effort estimate...' and 'PRIORITY TRIGGER: call AFTER `ado_analyze_workitem`'. Lists specific trigger phrases ('how long?', 'chiffre ce WI') and sequencing rules, clearly establishing when to use 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?

With only readOnlyHint in annotations, the description carries significant weight. It discloses the return structure (Detected D365 domain, Standard objects found, Existing extensions, Effort estimate) and explains the classification logic. It also notes the dependency on environment variable D365_CUSTOM_MODEL_PATH for extension detection. A minor gap is the lack of rate limit or latency guidance, but the operational behavior is well-documented.

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

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

Well-structured with clear section headers (WHEN, GAP/FIT CLASSIFIER, Triggers). Information is front-loaded with the trigger conditions. Uses formatting (emojis, bullet dashes) effectively to distinguish the four verdicts. Slightly verbose in the triggers list and classification explanation, but every sentence provides actionable guidance. The coordination note with `ado_analyze_workitem` is appropriately placed at the end as an operational caveat.

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

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

Despite having no output schema, the description thoroughly documents the return values (domain detection, KB objects, extensions, effort estimates). It covers all input alternatives (WI ID, plain text, comma-separated list) and their precedence. Given the complexity of D365 gap analysis and the absence of structured output metadata, the description successfully provides sufficient context for the agent to predict tool utility and interpret results.

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

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

While schema coverage is 100% (baseline 3), the description adds valuable workflow logic beyond the schema: it explains the mutual exclusivity between workItemId and requirementText (coordinating with sibling tool usage), clarifies that requirements (plural) overrides other inputs, and references the D365_CUSTOM_MODEL_PATH environment variable which affects behavior but isn't in the input schema. This provides essential context for correct parameter selection.

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

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

The description explicitly defines the tool's function as a 'GAP / FIT CLASSIFIER' for D365 F&O requirements, specifying the four possible verdicts (Standard Fit, Config Fit, Extension Fit, Gap) with clear visual indicators. It identifies the target resource (D365 requirements from ADO Work Items or plain text) and uses specific action verbs (analyse, classify). It also distinguishes itself from the sibling tool `ado_analyze_workitem` by specifying when to use each.

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

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

Provides explicit 'WHEN' conditions at the start, listing specific trigger phrases like 'gap analysis WI #N' and 'does D365 cover this'. Crucially, it includes negative guidance on when NOT to re-fetch: 'When a WI has already been analysed by `ado_analyze_workitem`... pass the requirement text directly... do NOT re-fetch'. This establishes clear precedence and coordination rules with sibling tools.

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

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

Beyond the readOnlyHint annotation, the description adds critical authentication requirements ('Requires DEVOPS_ORG_URL + DEVOPS_PAT'), return structure details ('Returns: PR ID, title, author...'), and fallback behavior ('Falls back to DEVOPS_PROJECT env var'). It compensates for the missing output schema by detailing return fields.

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-dense and well-structured with clear sections: priority triggers, core function, conditional logic, filters, returns, and auth. While the trigger phrase list is lengthy, it serves the necessary purpose of distinguishing from similar tools and supporting multilingual inputs. No wasted sentences.

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 6 optional parameters and no output schema, the description is remarkably complete. It details return values (compensating for missing output schema), authentication scope, environment variable fallbacks, and sibling tool relationships. Minor gap: could mention pagination behavior with the 'top' parameter.

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

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

With 100% schema coverage, the baseline is 3. The description adds workflow context for repositoryId ('If unknown, omit it and all repositories will be listed first') and groups filter parameters conceptually ('Filters: status...author...target branch'), adding usage semantics beyond raw schema definitions.

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

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

The description explicitly states 'List Pull Requests in an Azure DevOps Git repository' with specific verb and resource. It clearly distinguishes from siblings by explicitly stating 'NEVER call search_d365_code for PR listing requests' and contrasting with 'ado_analyze_pr_impact' for code impact analysis vs. listing.

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?

Excellent explicit guidance includes: priority trigger phrases covering multiple languages ('mes PR', 'liste des PR'), explicit exclusion of alternative tool ('NEVER call search_d365_code'), conditional logic ('If repositoryId is unknown, omit it'), and clear next-step recommendation ('Use ado_analyze_pr_impact with a PR ID').

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

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

No annotations provided, so description carries full disclosure burden. Successfully documents authentication requirements (DEVOPS_ORG_URL + DEVOPS_PAT with Work Items: Write permission) and safety protocol (explicit confirmation required). Minor gap: doesn't explicitly state this is a mutating write operation or describe return values/error states.

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?

Excellent structure with clear semantic headers (WHEN, PRIORITY TRIGGER, WARNING). Despite length, every sentence serves a purpose: trigger conditions, sibling dependencies, safety requirements, auth prerequisites, and workflow steps. No redundant or filler content.

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

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

No output schema exists, yet description omits what the tool returns upon success (e.g., comment ID, URL, or simple confirmation). While input parameters, auth, and workflow are comprehensively covered, the absence of return value documentation leaves a gap for a tool that creates resources.

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. Description adds meaningful semantic context by specifying that `commentText` should use 'the ready-to-post block from `ado_analyze_workitem`', creating clear linkage between sibling tools. Also implies `workItemId` context through workflow example ('Work Item #X').

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?

Explicitly states the tool posts/adds/saves comments to ADO Work Items using specific verbs. Clearly distinguishes from sibling `ado_post_pr_comment` by specifying 'Work Item' and establishes relationship with `ado_analyze_workitem` as a prerequisite workflow 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 explicit when-to-use ('WHEN: user explicitly asks...'), when-not-to-use (confirmation warning), and a detailed 4-step workflow sequence. Names specific trigger phrases ('post the analysis', 'ajoute en commentaire') and explicitly requires user confirmation before invocation.

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?

Strong disclosure given no annotations: explicitly states authentication requirements ('Requires DEVOPS_ORG_URL + DEVOPS_PAT') with specific permission scopes ('Pull Request Threads: Read & Write'), and safety constraints ('ALWAYS ask for explicit user confirmation'). Missing minor details about thread creation behavior or notification 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?

Well-structured with clear visual markers (WHEN, PRIORITY TRIGGER, WARNING) and numbered workflow steps. Front-loaded with trigger conditions. Slightly verbose but every sentence serves safety or operational clarity purposes. No redundant tautologies.

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?

Comprehensive for a write operation lacking annotations. Covers authentication, confirmation requirements, parameter relationships (inline vs general comments), and integration with analysis tools. Absence of output schema is noted; description appropriately focuses on input requirements and safety constraints rather than return values.

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

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

While schema has 100% coverage, description adds valuable workflow context specifying `commentText` should use 'the ready-to-post block from `ado_analyze_pr_impact`'. Clarifies the inline vs top-level comment distinction through the filePath/lineNumber relationship. Baseline 3 elevated by workflow integration guidance.

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

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

Clearly states the tool posts review comments to Azure DevOps Pull Requests with specific verbs ('post, add, or save'). Distinguishes from general analysis tools by mentioning the workflow with `ado_analyze_pr_impact`, though it doesn't explicitly differentiate from sibling `ado_post_comment` which may cause confusion.

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?

Exceptional guidance with explicit WHEN clause ('user explicitly asks to post'), priority trigger specifying exact call sequence ('call AFTER `ado_analyze_pr_impact`'), specific trigger phrases in multiple languages, and mandatory confirmation workflow. Clearly defines prerequisites and alternative tool integration.

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?

While annotations declare readOnlyHint=true, the description adds crucial behavioral context: the 50-item return limit, required environment variables (DEVOPS_ORG_URL + DEVOPS_PAT), and supported query modes (WIQL vs free-text vs shortcuts like 'my bugs'). It does not mention rate limits or caching behavior, preventing a perfect score.

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 substantial length, the description is efficiently structured and front-loaded: scope → purpose → triggers → exclusions → alternatives → usage patterns → returns → requirements. The extensive keyword lists are justified given the high risk of confusion with D365 siblings, though slightly verbose.

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 10 parameters and no output schema, the description compensates effectively by detailing the return payload ('max 50 work items with ID, title, type, state...') and auth prerequisites. It fully addresses the tool's position in a complex ecosystem with both Azure DevOps and D365 siblings.

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. The description elevates this by explaining the 'query' parameter's rich semantics: specific shortcuts ('bugs', 'recent', 'sprint'), WIQL support, and the critical constraint 'Use '*' with filters only'—usage guidance not inferable from the schema alone.

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

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

The description opens with a clear, specific verb ('Query') and resource ('Work Items'), explicitly listing the covered types (Bugs, Tasks, FDDs, User Stories, CRs). The 'AZURE DEVOPS ONLY' prefix immediately distinguishes it from the D365-focused siblings like search_labels and search_d365_code.

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

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

Provides exceptional guidance with an explicit '[~] PRIORITY TRIGGER' listing specific keywords (FDD, Bug, ticket, '#1234', etc.), followed by a 'NEVER use this tool for' section listing prohibited use cases (D365 labels, X++ code). Critically, it names specific sibling alternatives: 'For labels -> use search_labels' and 'For D365 code -> use search_d365_code'.

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?

While annotations indicate readOnlyHint=true, the description adds substantial behavioral context: specific detection targets (Chain of Command, event handlers, deprecated APIs, extensibility blocks), return format ('prioritized risk report with fix recommendations'), and prerequisite ('Requires D365_CUSTOM_MODEL_PATH'). Does not contradict annotations.

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

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

Information-dense and well-structured with clear sections (WHEN, Triggers, Detects, Returns). The trigger list is lengthy but serves a specific routing purpose. No redundant sentences, though the density prevents a perfect 5.

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

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

Lacks output schema but compensates adequately by describing return values ('prioritized risk report') and detection scope. For a complex analysis tool with zero parameters, the description provides sufficient context for invocation and expectation setting.

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?

Input schema has 0 parameters, establishing baseline 4 per rubric. The description mentions 'Requires D365_CUSTOM_MODEL_PATH' which clarifies environmental prerequisites without implying schema parameters.

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

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

The description uses specific verbs ('analyze', 'check', 'cross-references') and clearly identifies the resource (D365 F&O model upgrade impact). It distinguishes from siblings like 'ado_analyze_pr_impact' or 'search_d365_code' by focusing specifically on version upgrade compatibility and breaking changes.

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 clause ('upgrading D365 F&O to a new version') and extensive trigger keywords ('upgrade D365', 'will this break after upgrade', etc.) to guide invocation. However, lacks explicit 'when not to use' or named alternatives from the sibling list.

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

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

While annotations declare readOnlyHint=true, the description adds crucial behavioral context not present in structured fields: parallel execution model, maximum 6 query constraint, and the fact that results include 'FULLY loaded' objects with 'all chunks' (indicating complete source retrieval). No contradictions with readOnly annotation.

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

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

Well-structured with clear WHEN/INSTEAD/Triggers sections. Front-loaded with primary use case. The trigger list is slightly verbose but justified by multilingual support requirements. Every sentence provides actionable guidance or constraints without repetition of schema details.

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

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

Despite lacking output schema, description adequately explains return value semantics ('Results are equivalent to search_d365_code but returned together', 'FULLY loaded'). Covers critical behavioral constraints (max 6 queries, no follow-up calls needed) appropriate for a read-only batch search tool with 3 parameters.

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

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

Schema has 100% description coverage establishing baseline 3. Description adds value by clarifying the execution model ('each line becomes one parallel search') and reinforcing constraints ('Maximum 6 queries per call') that contextualize how the queries parameter is processed beyond the raw schema definition.

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 tool 'runs all queries in parallel' for 'multiple D365 objects or concepts simultaneously' and distinguishes from sibling search_d365_code by noting it handles 'each line' as a parallel search rather than sequential calls. Specific verb (batch search), resource (D365 objects), and scope (max 6) are clearly defined.

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 ('WHEN: you need context on multiple D365 objects...'), explicit alternative avoidance ('Use INSTEAD of multiple sequential search_d365_code calls'), and critical post-call guidance ('Do NOT follow up with get_object_details'). Includes trigger phrases in multiple languages for pattern matching.

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 readOnlyHint annotation, adds critical behavioral context: distinction between custom code (auto-fixing possible) vs standard objects (read-only analysis), and specific detection patterns. Does not mention auth needs or rate limits, but coverage of scope limitations is strong.

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 with clear section headers (WHEN, Triggers, Detects, NEVER). Trigger list is lengthy but justified by multilingual requirements. Front-loaded with usage conditions. Minor deduction for density of trigger keywords.

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?

Comprehensive for a complex analysis tool: covers detection scope, limitations (custom vs standard), output behavior (read-only analysis), and sibling differentiation. Adequately compensates for missing output schema by describing return behavior.

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%, providing complete parameter documentation. Description adds context that objects can be 'ANY D365 F&O object (custom or standard)' but does not elaborate on parameter syntax or methodName specifics 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?

States specific detection capabilities (N+1 queries, missing firstonly, row-by-row operations) and explicitly distinguishes from sibling 'validate_best_practices' for general code quality audits. Clear verb+resource+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?

Explicit 'WHEN' conditions with extensive trigger keywords (multilingual), explicit 'NEVER call' exclusion for general audits naming the alternative tool, and specific prerequisites ('Only call when user explicitly mentions...').

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

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

Annotations declare readOnlyHint=true, confirming safe read operations. The description adds critical behavioral context that output is 'plain business language' with 'no X++ or workflow engine jargon,' which defines the response format personality beyond the annotation. No contradictions present.

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 with clear sectioning: usage guidelines front-loaded (WHEN/NOT), followed by purpose declaration, then trigger examples. Slightly verbose trigger list but provides valuable multilingual invocation patterns. No filler content.

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

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

Despite no output schema, the description adequately explains return format ('plain business language'). Contextually complete for a single-parameter read tool, covering D365 domain specifics and output characteristics sufficiently for agent selection.

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?

Input schema has 100% description coverage for the single 'objectName' parameter with clear examples ('SalesTable', 'PurchTable'). The description does not add parameter semantics beyond the schema, but with full schema coverage, 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 explicitly states it explains D365 approval workflows in business language, covering who approves, workflow states, and approval/rejection outcomes. It clearly distinguishes from sibling `get_object_details` by specifying '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?

Provides explicit WHEN conditions ('user asks how an approval workflow works...'), explicit exclusions ('NOT for technical workflow class details'), and names the specific alternative tool ('use `get_object_details`'). Also includes extensive trigger phrases in multiple languages to identify 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 indicate readOnlyHint=true, and the description adds valuable behavioral context: it explains what data source is queried (compiled XRef DB), what the output represents (cross-reference profile), and lists all six categories of relationships analyzed. It does not contradict the read-only annotation.

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

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

The description is efficiently structured with the core purpose front-loaded, followed by coverage details, prerequisites, and trigger keywords. Every sentence delivers distinct value (function, scope, dependency, triggers) without redundancy, though the trigger list is lengthy.

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

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

Given the tool's complexity (analyzing six different relationship types across a compiled database) and absence of an output schema, the description adequately explains what the tool returns (cross-reference profile) and what information it covers. It could be improved by hinting at the output structure (tree vs list).

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

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

While the schema has 100% coverage documenting the parameters, the description adds semantic meaning by mapping the categories parameter values to their conceptual purposes (e.g., explaining that 'calls' represents call graphs, 'inheritance' covers base class chains, etc.), which aids agent understanding beyond the raw 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 explicitly states the tool finds callers of D365 F&O methods/classes and retrieves cross-reference profiles. It distinguishes itself from siblings (like find_references or search_d365_code) by enumerating specific reference kinds covered: Call graph, Usage, Inheritance, Interface, Overrides, and Attributes.

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 lists explicit triggers/keywords (including French variants) indicating when to invoke the tool. It also states the prerequisite requirement (xref_index.json.gz generated from DYNAMICSXREFDB). However, it lacks explicit guidance on when NOT to use this versus siblings like find_references or analyze_upgrade_impact.

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

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

Annotations only declare readOnlyHint=true. The description adds valuable behavioral context: it scans indexed AxDataEntityView objects, returns specific fields (entity name, public entity name, IsPublic, key fields, data sources), and conditionally generates XML templates. No contradiction with readOnlyHint as 'generate' appears to mean 'construct and return' rather than persist.

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/Triggers sections, but the description suffers from redundancy—generateIfMissing functionality is explained twice (beginning and end). The long list of trigger phrases in multiple languages adds bulk without adding semantic value for an AI agent selecting the tool.

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

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

No output schema exists, but the description compensates effectively by detailing the return structure (entity name, public entity name, IsPublic status, key fields, data sources). Given the 3-parameter complexity and minimal annotations, this provides sufficient context for invocation decisions.

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%, establishing baseline 3. The description adds workflow context for generateIfMissing ('auto-generate an AxDataEntityView XML template when no public entity is found') and implicitly clarifies tableName through concrete examples ('SalesTable', 'CustTable').

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 'Find D365 F&O data entities that expose a given table for OData/DMF integrations' with specific verb+resource. It distinguishes from siblings (which focus on code analysis, ADO, or general search) by specializing in D365 OData entity mapping and AxDataEntityView objects.

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

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

Provides explicit WHEN clause ('developer needs to integrate via OData') and trigger phrases for invocation detection. Explains conditional behavior with generateIfMissing. Lacks explicit 'when not to use' or named alternatives, though the domain specificity makes alternatives less critical.

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

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

Annotations only declare readOnlyHint=true. The description adds substantial behavioral context: it discloses the tool matches against a 'built-in database of common errors', resolves 'D365 label IDs from error text', and 'searches the indexed codebase'. It also specifies the return values (root causes, step-by-step resolution, label matches, source code locations) despite no output schema being present.

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 with clear sections: WHEN clause (front-loaded), trigger lists for both audiences, core functionality, prerequisite instruction ([~] note), and parameter guidance. Despite length, every sentence earns its place—the trigger lists are essential for routing, and the prerequisite note prevents errors.

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

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

Given no output schema, the description adequately explains returns (root causes, resolutions, source locations). It covers the prerequisite workflow, distinguishes from sibling `search_labels`, and explains the dual-audience behavior. Complete for a tool of this complexity interacting with multiple data sources.

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 description coverage, the baseline is 3. The description adds critical semantic guidance for errorOrSymptom regarding the prerequisite workflow with label IDs, and clarifies audienceType usage ('Set audienceType='business' for a plain-language explanation targeted at end users'). The examples in the description reinforce 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 explicitly states the tool 'Find known D365 F&O error patterns matching an error message or symptoms description' with specific capabilities (matching against built-in database, resolving label IDs, searching codebase). It clearly distinguishes from sibling `search_labels` by specifying when to use that tool first for label resolution.

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

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

Provides explicit 'WHEN' triggers for both developer and business audiences with specific phrases ('fix this error', 'what does this error mean'). Explicitly names alternative tool `search_labels` with prerequisite condition: 'When the error text contains a D365 label ID... call `search_labels` 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 declare readOnlyHint=true (safe read operation). Description adds valuable behavioral context by specifying exactly what types of extension objects are found and emphasizing 'ALL' (comprehensive search). Does not contradict annotations. Minor gap: no mention of return structure or search depth limits.

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?

Highly structured and front-loaded: WHEN clause first, followed by Triggers, main function, and exclusion clause. Every segment earns its place. Dense but efficient packing of usage conditions, domain terminology, and sibling differentiation in minimal 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 single-parameter read-only search tool with no output schema, the description is complete. It provides essential D365/AX domain context (specific extension object types), clear usage preconditions, and explicit sibling differentiation. No critical gaps given the tool's simplicity.

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 has 100% description coverage with examples (SalesTable, SalesFormLetter). Description references 'base object' reinforcing the parameter's role, but does not add syntax details, case sensitivity rules, or format constraints beyond what the schema already provides. Baseline 3 appropriate for high schema coverage.

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

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

Specific verb 'Finds' + exact resource types (AxClassExtension, AxTableExtension, AxFormExtension, CoC classes, event handlers) + scope 'for a base object'. Explicitly distinguishes from sibling 'find_references' by stating 'NOT for general references'.

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?

Excellent explicit guidance: 'WHEN: before modifying an object' defines the trigger context, and 'NOT for general references -- use find_references for that' names the specific alternative. Multilingual trigger keywords ('extensions de', 'CoC sur') further clarify 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 declare readOnlyHint=true (safe operation), and the description adds critical performance context: 'Full index scan (O(1M+) chunks) -- EXPENSIVE' and complexity comparison to find_callers. Also discloses automatic dual-format searching for label IDs (@SYS vs @SYS:). Does not mention rate limits or caching behavior, preventing a perfect score.

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 length, every sentence serves a purpose in distinguishing this from 30+ siblings. Excellent structure with front-loaded WHEN triggers, capitalized section headers (PREFER, NEVER, WORKFLOW), and zero redundancy. Length is justified by complexity, though slightly more compact phrasing possible.

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

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

Given no output schema and high sibling complexity, the description comprehensively covers usage patterns, performance implications, and return semantics (referencing objects, call sites). Missing explicit description of return structure (fields, format), which would be necessary for a 5 without 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?

With 100% schema coverage (baseline 3), the description adds meaningful examples for 'name' parameter ('SalesTable', 'validateWrite') and explains label ID format variations. It contextualizes maxResults implicitly through performance warnings. Could explicitly map parameters to use cases (e.g., 'use locationsPerObject to limit call sites per referencing 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?

Description explicitly defines the tool's purpose as impact analysis ('what breaks if I change X?', 'where is this used?') with specific verb+resource combinations. It clearly distinguishes from siblings by contrasting O(1M+) complexity against find_callers' O(1) and explicitly stating 'NEVER call for...' scenarios that overlap with get_object_details or search_d365_code.

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

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

Exceptional guidance including explicit WHEN triggers (multiple languages), capitalized 'NEVER' exclusions for identification queries, 'PREFER find_callers' directive with performance rationale, and specific step-by-step WORKFLOW for label IDs. Clearly maps to sibling tools (find_extensions for CoC, search_labels for text lookup) eliminating ambiguity.

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

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

Beyond the readOnlyHint annotation, the description discloses bidirectional relationship discovery (outgoing AND incoming back-references) and internal implementation details (delegation to get_relation_graph when relation index is loaded). This helps the agent understand result composition and caching behavior. Minor gap: no mention of performance characteristics or result format specifics.

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 with clear section markers (WHEN, Triggers, Returns, ALWAYS, Note). The extensive multilingual trigger phrase list, while lengthy, serves a specific purpose for LLM pattern recognition. The critical usage constraints are prominently placed at the end. Minor deduction for the length of the trigger list which could potentially be condensed.

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

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

Despite lacking an output schema, the description compensates by detailing what the tool returns (specific relation types including DeleteAction and DataSource). It also clarifies the tool's relationship to the discovery workflow (pre-code generation). Could improve by indicating return format (e.g., graph vs list) or pagination behavior.

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 description coverage (objectName fully documented with examples like 'SalesTable'), the description appropriately relies on the schema. It does not redundantly explain the parameter but implicitly reinforces its purpose through the context of 'finding relationships for' objects. Baseline 3 is appropriate when schema carries the 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 explicitly states the tool retrieves 'ALL relations, schema, or foreign keys of a D365 object' and details the specific return types (outgoing FK/DeleteAction/DataSource relations AND incoming back-references). It clearly distinguishes itself from get_relation_graph by explaining the delegation relationship and warning against redundant calls.

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?

Exceptional guidance provided: explicit 'WHEN' clause with multilingual trigger phrases, mandatory instruction 'ALWAYS call this BEFORE generating any code that touches multiple objects', and clear exclusion 'do NOT call both find_related_objects AND get_relation_graph'. This leaves no ambiguity about invocation timing and 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?

Annotations declare readOnlyHint=true. Description adds valuable context: diagrams render directly in Copilot/Claude/markdown viewers, sources data from D365 F&O knowledge base, and explains why flow diagrams are disabled (CoC and event handlers make static trees misleading). Minor gap: no mention of performance characteristics or caching.

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

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

Well front-loaded with WHEN clause and triggers. Information density is high but organized logically: triggers → purpose → diagram types with differentiation → disabled feature note. The trigger list is somewhat long but actionable. Every sentence provides selection or invocation 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?

No output schema exists, but description clarifies output is Mermaid diagram syntax that renders in chat/markdown viewers. With 4 parameters (2 required) fully documented in schema and clear behavioral context, the definition is complete enough for correct invocation, though explicitly stating 'returns Mermaid markdown string' would improve 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?

With 100% schema coverage, baseline is 3. Description adds significant value by explaining diagramType options ('er' vs 'security' vs disabled 'flow') and providing objectName examples ('SalesTable', 'SystemAdministrator') in the schema description. Effectively compensates for lack of enum constraints 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?

Description explicitly states it generates visual Mermaid diagrams from D365 F&O knowledge base data, specifying two diagram types (ER and security). It clearly distinguishes from sibling tool `trace_security_chain` by stating this tool is for VISUAL diagrams while the sibling provides structured text chains.

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?

Excellent guidance: explicit WHEN clause ('generating a visual diagram'), trigger keyword list, and explicit alternative naming ('use `trace_security_chain` instead' for text chains). Also clarifies when NOT to use by noting 'flow' is disabled due to misleading static call trees in D365.

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

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

Annotations declare readOnlyHint=true (safe read operation). The description adds valuable behavioral context by detailing the seven specific sections that will be generated. Does not contradict annotations; 'generates' here means returns composed content, not server-side mutation.

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

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

Uses structured headers (WHEN, NOT, Sections generated, Triggers) that front-load critical information. No wasted words; the trigger examples and section list are dense with useful signal.

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

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

No output schema is present, but the description compensates effectively by enumerating the seven FDD sections that will be returned. Would benefit from stating the output format (e.g., markdown), but adequately complete for a 3-parameter generation 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% with clear descriptions for all three parameters (objectName examples, context purpose, language options). Description does not add parameter-specific semantics beyond the schema, but none are needed given the 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 explicitly states it 'Produces a structured FDD ready for review and sign-off' and lists specific generated sections (Purpose, Business Context, Data Fields, etc.). It clearly distinguishes from siblings by stating 'NOT for developer technical docs -- use `get_object_details` for that.'

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

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

Provides explicit WHEN triggers ('user asks to write or generate a Functional Design Document...') and explicit exclusion ('NOT for developer technical docs'). Names the specific alternative tool `get_object_details` for the excluded use case.

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?

While annotations declare readOnlyHint=true, the description adds important behavioral context: it explains that the tool 'Uses real field names, relations, and indexes from the knowledge base' to produce output, warns that 'The generated X++ is a template' requiring adaptation, and specifies that it 'Returns side-by-side X++ and SQL with explanations.' There is no contradiction with the read-only annotation.

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

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

The description is well-structured and front-loaded with the 'WHEN:' clause and trigger keywords, followed by capability declarations and '[!]' warning blocks. While lengthy, every section serves a distinct purpose: invocation triggers, functional scope, workflow prerequisites, and output warnings. The density of actionable guidance justifies the 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 absence of an output schema, the description adequately compensates by specifying that it 'Returns side-by-side X++ and SQL with explanations.' It addresses the complex 8-parameter surface by explaining the auto-detection behavior when using natural language descriptions and the critical prerequisite of calling find_related_objects for joins. It appropriately covers production safety concerns given the code-generation nature of the 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 description coverage, the baseline is 3. The description adds value by providing a concrete natural language example ('find all open sales orders for customer 1001 with CustTable join') illustrating how the description parameter enables auto-detection of other fields. It also maps supported features (field selection, multi-table joins, WHERE filters) to the parameter capabilities, clarifying interaction patterns beyond individual parameter definitions.

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

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

The description explicitly states the tool 'Generate[s] both X++ select statements and equivalent T-SQL queries for D365 F&O tables,' providing a specific verb (generate), resource (queries), and domain scope (D365 F&O). It clearly distinguishes itself from sibling tools by specifying that find_related_objects should be called first for multi-table joins, carving out its specific role in the workflow.

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 includes an explicit 'WHEN:' clause listing specific triggers such as 'X++ select', 'generate a query', and 'write a select statement'. It provides clear workflow guidance with '[!] For multi-table joins, call find_related_objects... FIRST,' explicitly naming the prerequisite sibling tool. It also includes warnings about production usage ('adapt it to your custom code context before using in production').

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

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

Annotations declare readOnlyHint=true; the description adds crucial behavioral context that this generates code using 'REAL field names and method signatures from the knowledge base' and warns that output 'rarely compiles without adaptation.' It also clarifies the distinction between table and class generation behaviors.

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 with clear sections (WHEN, Triggers, main purpose, warnings [!], parameter details). Front-loaded with use case. Slightly dense but every sentence provides distinct value—no repetition of schema or annotation data.

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 generation tool without output schema, the description adequately explains output behavior (specific test methods for tables vs stubs for classes) and operational constraints (custom model path only). Covers prerequisites and limitations sufficiently for agent selection.

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%, establishing baseline 3. The description adds valuable usage context: testScenarios should be 'supplied by the functional consultant' with semicolon separation, and implies methodName logic ('If not provided, generates tests for all testable methods').

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

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

The description explicitly states it 'Generate[s] X++ SysTest unit test code for a CUSTOM D365 F&O object'—specific verb, technology, and resource type. The 'WHEN' clause and trigger phrases clearly distinguish this from sibling analysis tools like 'find_references' or 'analyze_upgrade_impact'.

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?

Excellent guidance including explicit WHEN clause ('developer needs to write or scaffold unit tests'), required prerequisites ('REQUIRED: provide test scenarios... supplied by the functional consultant'), and clear limitations ('Only meaningful on custom/extension code', 'generic template rarely compiles without adaptation').

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 provide readOnlyHint=true, indicating this is a safe read operation. The description adds valuable behavioral context beyond this: it explains that the tool uses 'REAL metadata from the KB' for accuracy, specifies what different template types mean (e.g., 'coc' = Chain of Command class), and mandates a prerequisite action ('ALWAYS call get_object_details first'). While it doesn't mention rate limits or authentication needs, it provides significant implementation details that annotations don't cover.

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 appropriately sized and front-loaded, starting with the 'WHEN' clause for immediate context. It efficiently lists triggers and explains template types without unnecessary elaboration. While slightly dense due to the list of triggers and acronym explanations, every sentence serves a clear purpose in guiding usage and understanding, with minimal waste.

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

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

Given the tool's complexity (code generation with metadata dependencies) and the absence of an output schema, the description does well by explaining template types, prerequisites, and behavioral context. It could be more complete by hinting at the output format (e.g., generated code snippets) or error handling, but it covers key aspects like usage scenarios and integration with other tools (get_object_details), making it largely sufficient for agent understanding.

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, so parameters are well-documented in the schema itself. The description adds some semantic context by explaining acronyms like 'coc' and 'table_extension', and mentioning that 'objectName' examples include 'SalesTable'. However, it doesn't provide additional syntax, format details, or constraints beyond what the schema already specifies, meeting the baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: 'generates ready-to-use X++ code' for extensions/customizations. It specifies the resource (X++ code) and verb (generates), and distinguishes itself from siblings by focusing on code generation rather than analysis, searching, or other operations. The mention of using 'REAL metadata from the KB' adds specificity about the source of information.

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 usage guidelines: it starts with 'WHEN: writing an extension or customization' and includes specific triggers like 'generate extension' or 'write a CoC class'. It also names an alternative tool ('ALWAYS call get_object_details first') and gives exclusionary advice (verify object existence before use). This covers when to use, when not to use (without verification), and alternatives clearly.

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

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

Annotations indicate readOnlyHint=true, confirming safe read operations. Description adds valuable behavioral context beyond annotations: it discloses the disk merge priority behavior ('disk takes priority') and explains the critical two-step calling pattern required to avoid redundant API calls ('Do NOT call a third time').

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 substantial length, every sentence serves a distinct purpose—defining triggers, scope, disk merging behavior, parameter interaction patterns, and exclusions. Information is front-loaded with WHEN conditions and trigger examples. Minor deduction only because density requires careful parsing, but no waste is present.

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

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

For a tool with complex behavioral patterns (two-step calling, disk merging) and no output schema, the description comprehensively explains return contents (fields, methods, source code) and operational constraints. The explicit workflow instructions prevent common misuse patterns without needing an output schema definition.

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

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

While schema coverage is 100% with adequate parameter descriptions, the tool description adds crucial semantic context about parameter interaction: it explains the temporal workflow ('first without methodName... then again with') and the behavioral difference between signatures vs. full body returns that raw schema cannot express.

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 tool retrieves 'complete details: all fields, methods, relations, indexes, source code, and metadata' for D365 objects. It precisely defines the scope (exact object name required) and distinguishes from siblings by explicitly naming search_d365_code and list_objects as alternatives for different use cases.

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

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

Provides explicit WHEN conditions ('you know the EXACT object name'), trigger patterns ('PascalCase D365 object name'), and detailed workflow guidance including the 'CORRECT and INTENDED two-step pattern' for method retrieval. Clearly states negative constraints ('NOT for searching', 'NOT for listing') with specific alternative tools.

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

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

The description adds valuable behavioral context beyond the readOnlyHint annotation. It specifies the JSON return structure (status, indexed chunk count, loaded version, custom model path) and mentions it's triggered by status queries. While the annotation covers safety, the description provides operational details about what information is returned.

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 clear sections (WHEN, Triggers, Returns) and every sentence adds value. It's front-loaded with the primary purpose and uses bullet-like formatting without unnecessary words. The information density is high with zero wasted 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 parameterless read-only tool, the description provides excellent context: clear purpose, usage guidelines, return format, and trigger examples. The only minor gap is that without an output schema, the exact structure of the JSON return isn't formally defined, but the description gives a good overview of what to expect.

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

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

With 0 parameters and 100% schema description coverage, the baseline would be 4. The description reinforces this by not mentioning any parameters, which is appropriate for a parameterless tool. It focuses instead on the tool's purpose and return values.

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

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

The description explicitly states the tool's purpose: checking server status, D365 version, and custom model path. It uses specific verbs ('checking', 'returns') and clearly distinguishes this health monitoring tool from its many siblings focused on code analysis, task management, and other functions.

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 usage guidance with a 'WHEN:' section listing specific scenarios (checking server status, loaded version, custom model path) and concrete trigger examples ('status', 'is the server ready', 'how many chunks'). This gives clear context for when to use this 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?

Annotations declare readOnlyHint=true. Description adds valuable behavioral context beyond annotations: 'Reads the file system directly -- always reflects the latest uncommitted state.' This discloses critical timing/visibility characteristics (uncommitted changes) that annotations don't capture.

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 with logical flow: triggers → core action → behavioral note → configuration. Front-loaded with invocation patterns. Slightly verbose on trigger enumeration but each example aids agent routing. No redundant sentences.

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 tool without output schema, description adequately indicates return content ('List all D365 F&O objects'). Covers configuration prerequisites (path specification methods). Given the single optional parameter and read-only nature, description provides sufficient context for invocation.

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

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

Schema has 100% description coverage for customModelPath. Description adds important usage semantics: explaining the hierarchy between parameter value, header configuration, and server-configured path ('Overrides the header'), and noting the persistent config option via .mcp.json.

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 tool 'List all D365 F&O objects in the custom/extension model directory' with specific domain context. The WHEN clause and trigger phrases ('list my custom objects', 'show ISV objects') precisely distinguish it from generic siblings like 'list_objects' by emphasizing the custom/extension model 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?

Provides explicit WHEN clause ('developer wants to see what custom/extension objects exist') and specific trigger phrases for invocation. Documents configuration alternatives (parameter vs D365-Custom-Model-Path header). Lacks explicit contrast with sibling tool 'list_objects', though the custom model scope is implicitly distinguished.

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

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

With readOnlyHint: true in annotations, the description adds valuable behavioral context: it warns that this performs a 'Full index scan' (implying potential performance cost), and explains default behavior when 'no filters are given and a custom model is configured.' It does not contradict the read-only annotation.

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

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

The description is well-structured and front-loaded with the 'WHEN:' clause. While lengthy, every sentence serves a distinct purpose: intent recognition (triggers), behavioral scope (full scan), use case (discovery), and exclusions. The multi-language trigger examples are justified for intent recognition.

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 100% schema coverage and readOnly annotation, the description is appropriately complete. It explains the return scope ('returns EVERY matching object') without requiring an output schema, and enumerates specific AOT types (tables, classes, forms, enums) that align with the aotType parameter.

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

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

Schema coverage is 100%, establishing a baseline of 3. The description adds value by mapping the parameters to concrete use cases mentioned in the triggers (e.g., 'tables', 'classes', 'ALM' model), reinforcing that aotType filters by object category and modelName filters by module.

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

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

The description explicitly states the tool lists 'ALL objects of a given type or in a given model' with a 'Full index scan.' It clearly distinguishes this from siblings by specifying it returns 'EVERY matching object, not just top search results,' contrasting with search_d365_code.

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

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

Exceptional guidance with explicit WHEN/NOT directives. It names specific sibling alternatives: 'NOT for a single object -- use get_object_details' and 'NOT for natural language search -- use search_d365_code.' It also provides concrete trigger phrases ('list all tables in ALM', 'quels objets dans le modèle') to help the agent recognize intent.

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 read-only (readOnlyHint: true), which is consistent. Description adds valuable behavioral context: output format (Mermaid diagram), behavioral split between known processes (showing security roles/reports) versus generic object tracing, and performance note that sibling tool is faster for single-object relations.

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 length, every sentence earns its place: WHEN clause, trigger keywords, dual-mode behavior explanation (known vs unknown processes), output specification, special parameter value, and sibling contrast. Front-loaded structure makes scanning efficient.

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

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

For a complex tool with no output schema, description adequately compensates by specifying the Mermaid diagram output and detailing the two operational modes. However, absence of output schema prevents a 5, as return structure details (e.g., whether it returns raw graph data or rendered image) remain unspecified.

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, baseline is 3. Description adds significant value by enumerating the 8 known process names that trigger special handling (Order-to-Cash, Procure-to-Pay, etc.) and documenting the special 'list' parameter value behavior, which is not obvious from schema alone.

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

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

Description explicitly states it maps business processes to 'complete object chain' or traces dependencies, producing a 'Mermaid process flow diagram'. It clearly distinguishes from sibling `find_related_objects` by stating this is for full process flows versus single object FK relations.

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?

Excellent guidance with explicit 'WHEN:' clause listing triggers (e.g., 'Order-to-Cash', 'map the process'), specific instruction to use 'list' for available mappings, and clear exclusion criteria ('NOT for a single object's FK relations only -- use `find_related_objects`').

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

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

Annotations declare readOnlyHint=true, but the description adds crucial behavioral context: 'Returns ALL chunks (metadata, Declaration, methods) for the top-scoring objects' vs 'Lower-scoring results return a short preview,' and 'No follow-up get_object_details call is needed.' This discloses the tiered return behavior not indicated in annotations. Does not mention rate limits or auth requirements.

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 lengthy but information-dense and front-loaded with WHEN clauses. Every section serves a distinct purpose: trigger keywords (including French), behavioral explanation, return format, and sibling distinctions (~20 siblings). While verbose, the length is justified by the need to prevent confusion with ADO tools and other search utilities.

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 no output schema, the description fully explains the return structure (full chunks vs previews), covers the domain scope (D365 F&O, X++), and provides complete guidance on tool selection among numerous siblings (list_objects, get_object_details, batch_search, ado_* tools). Sufficient 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% (all 4 parameters fully documented with types, defaults, and examples). The description references 'top-scoring objects' implicitly mapping to topObjects parameter, but does not explicitly elaborate on parameter semantics beyond the schema. With high schema coverage, 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 explicitly states the tool 'Search[es] the D365 F&O knowledge base for X++ code, tables, classes, forms... using natural language or partial names.' It clearly distinguishes from siblings: 'NOT for listing all objects... use list_objects' and 'NOT when the exact name is known... use get_object_details.' Specific verb, resource, and scope with clear sibling differentiation.

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 exhaustive when/when-not guidance: explicit triggers ('find', 'search', 'chercher'), exclusions ('NEVER use this tool when the user mentions: FDD, Workitem...'), and alternatives ('use batch_search instead' for multiple concepts, 'use get_object_details' for exact names). Also includes operational constraints ('NEVER call search_d365_code twice in the same conversation turn').

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

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

Beyond the readOnlyHint annotation, the description adds critical behavioral details: language loading performance ('first call ~15s, then instant'), startup vs on-demand language availability, automatic normalization of label formats (@SYS:12345 vs @SYS12345), and data scale (1M+ entries). No contradiction with readOnlyHint=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?

Information-dense but well-structured with clear functional separation: core purpose, bidirectional examples, format normalization, scale, workflow, and performance notes. Each sentence serves a distinct purpose, though the density slightly impacts scannability.

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?

Excellent coverage of input behavior and workflow integration. Minor gap: lacks explicit description of return value structure (e.g., array format, specific fields returned) given the absence of an output schema, though the bidirectional explanation implicitly clarifies what data is returned.

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

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

With 100% schema coverage, the baseline is 3. The description adds valuable context about query parameter formats (short vs colon form) and language parameter performance implications (startup vs on-demand loading), enhancing understanding beyond the raw schema definitions.

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

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

The description explicitly states the tool searches D365 F&O labels bidirectionally (text-to-ID and ID-to-text) with concrete examples ('Sales order' → '@SYS12345'). It distinguishes itself from sibling 'find_references' by explicitly stating the workflow sequence, clearly delineating responsibilities between the two 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?

Contains an explicit 'WORKFLOW:' section stating exactly when to use this tool ('call search_labels first to resolve the label text, then call find_references'), providing clear sequencing and alternative selection criteria that directly reference a sibling 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 declare readOnlyHint=true, confirming this is a safe suggestion tool. Description adds valuable context about return values ('ranked candidate EDTs with their base type, label, and model') which compensates for the missing output schema. Does not mention rate limits or caching, but covers the essential behavioral contract.

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?

Highly structured with 'WHEN:' prefix and 'Triggers:' list. Every sentence serves a distinct purpose: usage context, trigger phrases, business justification, invocation timing, and return value description. No redundant or wasted 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?

Comprehensive for a recommendation tool: explains D365 domain context, best practice rationale, when to invoke, and return value structure. Lacks output schema but description compensates by detailing the return format. Would be 5 with formal output schema, but adequately complete as-is.

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 has 100% description coverage with detailed explanations for fieldName, purpose, baseType, and topK. The description references 'field name or concept' and 'purpose' in the usage context but does not add parameter-specific semantics beyond what the schema already provides. Baseline 3 is appropriate given complete schema documentation.

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 clearly states the specific action ('find the best existing D365 EDT to extend') and resource (EDTs vs raw primitives). It distinctly differs from siblings like 'search_d365_code' or 'find_references' by focusing on type selection/best practices rather than code search or 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?

Excellent explicit guidance: 'WHEN: adding a new field to a table', 'Call BEFORE declaring any field with a primitive type', and specific trigger phrases ('what EDT for', 'which EDT should I extend'). Also explains the business rule ('D365 best practice mandates EDT reuse').

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

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

Annotations declare readOnlyHint=true (safe operation). Description adds valuable behavioral context: lists specific analysis patterns performed (long methods, deep nesting, row-by-row operations, etc.) and discloses output format ('Returns before/after code examples'). Does not contradict annotations.

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

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

Well-structured with front-loaded 'WHEN' clause, explicit triggers section, and bulleted analysis patterns. Information-dense but organized. The multilingual trigger ('améliorer le code') and specific pattern list add value despite 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?

For a 2-parameter tool with simple schema and no output schema, description adequately compensates by detailing return value type (before/after examples) and specific analysis capabilities. The scope limitation (custom code only) is critical contextual completeness for D365 environments.

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%, establishing baseline 3. Description adds meaningful constraint that tool 'Only runs on custom/extension code (D365_CUSTOM_MODEL_PATH)', which semantically restricts valid inputs for objectName parameter to custom model objects only, beyond what the schema examples show.

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 uses specific verb phrase 'Suggest concrete refactoring actions' with clear resource 'custom D365 F&O X++ code'. The '[!] Only runs on custom/extension code' constraint effectively distinguishes it from sibling analysis tools like validate_best_practices or search_d365_code by restricting scope to D365_CUSTOM_MODEL_PATH.

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' clause identifies trigger scenarios (before PR merge/code review). Lists specific keyword triggers ('refactor', 'clean up', 'nested ifs', etc.). Clearly states exclusion criteria: 'Refactoring standard Microsoft code is not actionable', providing clear when-not-to-use guidance.

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

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

Annotations declare readOnlyHint=true; description adds substantial behavioral context including confidence classification (High/Medium/Low), specific output structure (Optimization section, cost estimates), grant-level awareness logic, and validation requirements against Microsoft Licensing Guide. Does not contradict annotations.

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

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

Despite length, the description is information-dense and well-structured with front-loaded WHEN clause, bulleted triggers, clear section flow (build logic → confidence → optimization → validation → usage patterns), and zero filler. Every sentence addresses selection, invocation, or output expectations.

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

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

For a complex licensing analysis tool with no output schema, the description adequately explains return structure (complete tree with license classifications), auxiliary outputs (optimization section, cost estimates), and reliability indicators. Would benefit from explicit output format/schema description, but covers essential behavioral outputs comprehensively.

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 has 100% description coverage with clear parameter descriptions. The description reinforces the 'ONE role' constraint (guiding roleName usage) and mentions Entry Points (relating to maxEntryPoints), but does not add significant semantic detail beyond what the schema already provides, warranting the baseline score for high-coverage 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 explicitly states it 'Builds the COMPLETE tree for ONE role: Role -> Duties -> Privileges -> Entry Points' and clearly distinguishes from sibling tool `trace_security_chain` for 'pure technical duty/privilege/entry-point chain without licence inference'. Specific verb+resource+scope is present with D365 licensing context.

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 clause ('security design, licence audit, or what licence does this role require?'), lists specific trigger keywords ('arborescence du rôle', 'role tree', etc.), and explicitly names the alternative tool `trace_security_chain` for technical-only traces. Also advises on multi-role scan patterns ('call multiple times -- once per role').

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

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

Annotations declare readOnlyHint=true; description adds valuable behavioral context including the specific traversal path ('Role -> Duties -> Privileges -> Entry Points -> Table/Form Permissions') and the functional difference between technical mode (with IDs) and businessLanguage=true mode (plain-language capabilities). Could mention 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?

Information-dense but well-structured with clear sections (WHEN, Triggers technical/business, Traverses, NOT FOR). Trigger lists are lengthy but necessary for accurate LLM routing. No redundant repetition of schema details.

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 security chain traversal tool with no output schema, the description adequately explains what gets returned (technical chain vs business capabilities) and the scope of data covered. Sibling differentiation is complete. Minor gap: doesn't describe output format structure.

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%, establishing baseline 3. Description elevates this by adding functional semantics for businessLanguage parameter: 'Set businessLanguage=true for plain-language capability list (no Duty/Privilege IDs)', explaining the consequence of the parameter beyond the schema's type/default.

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

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

Description explicitly states the tool retrieves the 'TECHNICAL chain from Role/Duty/Privilege to Entry Points and Table/Form permissions' and contrasts this with business-language explanations. It clearly distinguishes from sibling 'trace_role_license_tree' by stating it is 'NOT for licence cost inference per entry point'.

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 clause ('security audit -- need the TECHNICAL chain'), lists specific trigger phrases for both technical and business-language contexts, and explicitly names the alternative tool ('use trace_role_license_tree for that') for license cost inference scenarios.

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

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

Annotations declare readOnlyHint=true; the description adds valuable context about what gets analyzed (security vulnerabilities, transaction problems) and explains the auto-fixing constraint ('only possible on YOUR custom code'). However, it could clarify whether auto-fixing suggestions are returned or if the tool suggests without returning fix data.

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?

Excellent structure with clear section headers (WHEN, Triggers, Checks, NOT for). Information is front-loaded and dense without redundancy. The '[!]' warning format efficiently highlights critical constraints regarding custom vs. standard code.

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

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

Despite lacking an output schema, the description adequately explains return behavior (violation analysis, read-only for standard objects, severity filtering). For a validation tool with good annotations, this is sufficient, though mentioning the output format (list of violations vs. summary) would improve it further.

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

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

Schema description coverage is 100% (all 3 parameters have complete descriptions including types, defaults, and examples). The description does not add parameter-specific semantics beyond the schema, which is acceptable given the high schema coverage 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?

Description clearly states it performs best-practice audits and code review on D365 F&O objects, checking security, performance, transactions, and error handling. It explicitly distinguishes from sibling 'detect_performance_issues' by stating 'NOT for deep performance profiling... use detect_performance_issues for that.'

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 context ('code review, quality gate, or best-practice audit'), lists specific trigger keywords, and clearly identifies the alternative tool for excluded use cases. Also clarifies scope limitations (custom vs. standard objects) that determine output behavior.

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