ALM X++ MCP Server

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

Beyond the readOnlyHint annotation, the description discloses that the tool reads from the ADO REST API (not local git), handles un-merged and brand-new files, embeds full source by default, and is X++-centric with known limitations on AOT XML. It also clarifies permission requirements (DEVOPS_ORG_URL + DEVOPS_PAT with Code: Read). No contradiction with annotations.

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

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

The description is comprehensive but verbose, repeating the same warning against local git usage three times ('DO NOT fall back to local git show/git diff', 'NEVER run git'). While it is front-loaded with the trigger, the length and redundancy prevent it from being concise. Not every sentence earns its place.

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

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

For a complex tool with no output schema, the description covers all essential contexts: purpose, triggers, alternatives, behavior, limitations (metadata-only PRs, maxFilesDeep), output contents (source embedding, review comment), and post-tool workflow. It is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by elaborating on includeSource's purpose (enabling full semantic review without local checkout) and on maxFilesDeep behavior (larger PRs get summary). This goes beyond the schema descriptions, earning a 4.

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

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

The description opens with a specific verb+resource: 'Analyse the full D365 F&O code impact of a Pull Request.' It clearly differentiates from sibling tools by explicitly stating 'NEVER call search_d365_code when PR... is mentioned' and by outlining a distinct analysis workflow (BP, upgrade impact, extension conflicts). This makes the tool's purpose unambiguous.

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

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

The description provides a dedicated 'PRIORITY TRIGGER' section listing exact user phrases that should invoke this tool, and explicitly excludes alternatives ('NEVER call search_d365_code'). It also gives workflow guidance: 'After reviewing, call ado_post_pr_comment...' and warns against using local git commands. This is exemplary usage guidance.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: it returns raw structured context, not a finished analysis; lists the four categories of returned data; states environment variable requirements; and explicitly says it never posts comments. This fully discloses behavior and is consistent 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 lengthy but well-structured with clear headers and a front-loaded summary. Every section serves a purpose: trigger phrases, exclusions, return content, post-processing instructions, and environment requirements. It could be tightened, but the organization makes it easy to scan.

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

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

For a complex tool with no output schema, the description is exceptionally complete. It explains what the tool returns, what it does not do, how the agent should use the results, when to use it, when to avoid it, and the required environment variables. This fully equips an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter-level detail beyond the schema, but it does mention the required env vars (DEVOPS_ORG_URL, DEVOPS_PAT) which contextualize the parameters. It does not repeat or contradict schema descriptions.

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

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

The description states a specific verb and resource: 'Fetch a Work Item and assemble ALL technical context needed for D365 F&O expert analysis.' It clearly distinguishes itself from siblings by noting it is for work items (not PRs), and explicitly excludes label lookups and X++ code search, directing to alternative tools.

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

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

The description provides explicit priority trigger phrases, explicit 'NEVER for' exclusions, and names alternative tools (search_labels, search_d365_code). It also clarifies the tool's role as a context-gathering step and instructs the agent to never post comments on related work items, giving clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description fully carries the burden of transparency. It discloses substantive behaviors: automatic branch creation, child/related linking rules, auto-incrementing counter, embedded assignee/CC in description, language switching, and required permissions (DEVOPS_ORG_URL + DEVOPS_PAT). This is far more than a generic 'create' statement.

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

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

The description is long but logically structured with labeled sections (WHEN, Rules, LANGUAGE RULE, Requires). Each part contributes necessary behavior for correct execution, and the critical trigger information is front-loaded. Slight trimming could improve conciseness, but the structure earns its length.

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

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

For a 10-parameter tool with no output schema, the description covers triggers, naming conventions, branch creation, language handling, and required credentials. It does not describe return values (e.g., task ID/URL), which would improve completeness, but the provided context is sufficient for an agent to invoke the tool correctly in most cases.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema by explaining how `workItemId` determines naming/linking rules and that the `description` parameter should be written in the user's language. This enriches parameter understanding without repeating schema text.

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

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

Description opens with 'Create a D365 F&O development Task work item in Azure DevOps' and provides explicit trigger phrases, clearly distinguishing it from siblings like ado_update_workitem. The verb+resource+scope is specific and unambiguous.

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

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

Starts with 'WHEN' and lists concrete user triggers ('create task', 'start development on', etc.), which precisely indicates when to use this tool over others. It also covers language rules and credential prerequisites, giving clear guidance on invocation context.

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

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

Annotations already declare readOnlyHint=true, and the description adds context about internal methodology (KB signals, ADO history) and output content (per-phase hours, confidence, risk). It does not contradict annotations and offers meaningful behavioral detail beyond the read-only flag, though it could mention potential failure modes.

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

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

The description is well-organized with bolded section labels (WHEN, PRIORITY TRIGGER, Returns, Triggers) and front-loads the most critical usage condition. It is somewhat long due to the trigger list, but every sentence provides actionable info; minor redundancy in the trigger phrases.

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 complexity of an effort estimation tool and the absence of an output schema, the description fully covers what the tool does, when to use it (including after a specific sibling tool), and what it returns (per-phase breakdown, KB signals, confidence/risk, ready-to-paste estimate). This is sufficient for an agent to select and invoke it correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters (workItemId, project, focusObjects). The tool description does not add extra parameter guidance beyond the triggers, so the baseline of 3 is appropriate.

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

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

The description opens with 'Estimate D365 F&O development effort for a Work Item', using a specific verb and resource, and details the output (per-phase hour breakdown). It clearly distinguishes this from sibling tools like ado_analyze_workitem (analysis) and ado_create_task (creation) by focusing on estimation.

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' section states the user intent (effort estimate, chiffrage, development hours) and a 'PRIORITY TRIGGER' instructs to call AFTER ado_analyze_workitem. Trigger phrases like 'estimate this' and 'chiffre ce WI' provide clear, actionable guidance for when to invoke this tool.

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

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

The description adds substantial behavior details beyond the readOnlyHint annotation: it lists the exact return components (domain, standard objects, existing extensions, effort estimate, reasoning) and discloses the dependency on D365_CUSTOM_MODEL_PATH for extension detection. It also explains the input precedence logic, giving the agent a clear model of the tool's behavior.

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

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

The description is moderately long but well-organized with labeled sections (WHEN, verdict list, return list, triggers, note). Every section contributes meaningful information, and the front-loaded WHEN section helps agents quickly determine relevance. It is slightly verbose but appropriate given the tool's complexity.

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

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

With no output schema and moderate input complexity, the description covers all necessary aspects: triggers, input modes, return format, and a caveat about environment dependencies. It fully prepares an agent to invoke the tool correctly and interpret results, making it highly complete for its context.

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

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

Schema coverage is 100%, so all parameters are already described. The tool description adds value by clarifying the precedence relationship (requirements overrides both workItemId and requirementText) and the fallback behavior between workItemId and requirementText, which is not fully evident 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 clearly states the tool's function: analyzing a D365 F&O requirement (from an ADO Work Item or plain text) and classifying it into four explicit verdicts. This distinguishes it from sibling tools by focusing on fit/gap classification, not generic analysis or PR 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?

The description provides a dedicated 'WHEN' section and trigger phrases, making clear when to use the tool. It also gives a specific when-not (do not re-fetch with workItemId if already analyzed by ado_analyze_workitem) and guidance on selecting between input parameters. However, it does not explicitly reference alternative sibling tools, so it stops short of a perfect 5.

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

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

Beyond the readOnlyHint annotation, it discloses authentication requirements (DEVOPS_ORG_URL + DEVOPS_PAT with Code: Read scope), fallback behavior when repositoryId is omitted, and the exact return fields (PR ID, title, author, source->target branch, review status, linked work items, creation date).

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?

Although the trigger list is somewhat long, every sentence serves a purpose: trigger phrases, exclusions, purpose, behavior, returns, related tool, and auth. Information is front-loaded and well-structured.

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

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

With no output schema, the description lists return fields explicitly. It also covers authentication, filters, and fallback behavior, making it complete for an agent to invoke correctly.

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

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

Input schema covers 100% of parameters with detailed descriptions, including the repositoryId fallback behavior. The description only summarizes filters and does not add meaningful semantic information beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'List Pull Requests in an Azure DevOps Git repository' with a specific verb and resource. It also distinguishes itself from sibling tools by explicitly saying 'NEVER call search_d365_code for PR listing requests' and pointing to ado_analyze_pr_impact for impact 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?

Provides a PRIORITY TRIGGER with specific phrases to detect when to use this tool, and explicitly forbids using search_d365_code. It also instructs to use ado_analyze_pr_impact for impact analysis, giving clear when-to-use/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 no annotations, the description carries the full burden and discloses critical behavioral traits: it mandates explicit user confirmation before invocation, states required permissions (DEVOPS_PAT with Work Items: Write), and specifies a strict ordering after analysis. This goes beyond basic side-effect statements.

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 labeled sections (WHEN, PRIORITY TRIGGER, WARNING, Recommended workflow, Requirements). Every sentence contributes essential operational information with no redundancy or fluff.

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

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

For a simple write operation with no output schema, the description covers when to use, prerequisites, required permissions, confirmation protocol, and integration with a prior analysis tool. Return value details are not necessary given the tool's straightforward action.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds value by instructing to use the ready-to-post block from 'ado_analyze_workitem' for commentText and clarifying the project fallback to DEVOPS_PROJECT env var, going beyond schema details.

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

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

The description clearly states 'WHEN: user explicitly asks to post, add, or save a comment to an ADO Work Item,' identifying the specific verb, resource, and scope. This distinguishes it from sibling tools like 'ado_post_pr_comment' which targets pull requests.

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 trigger conditions ('user explicitly asks to post...') and a recommended workflow involving 'ado_analyze_workitem' and user confirmation. It lacks explicit when-not-to-use alternatives (e.g., for PR comments), but the guidance is otherwise clear and actionable.

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

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

With no annotations, the description carries the full behavioral burden. It discloses authentication requirements (DEVOPS_ORG_URL + DEVOPS_PAT with scopes 'Pull Request Threads: Read & Write'), mandates user confirmation, and instructs to use the 'ready-to-post block' from the analysis tool, providing important behavioral and safety context.

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

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

The description is concise and well-structured: it leads with WHEN, then PRIORITY TRIGGER, WARNING, workflow, and credentials. Every sentence adds value with no repetition or fluff.

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

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

Given no annotations and no output schema, the description is remarkably complete. It covers when to invoke (after analysis), the prerequisite workflow, confirmation requirement, auth needs, and the expected content source. It lacks only an explicit return value description, but for a simple post-comment action this is not a critical gap.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The tool description does not add significant parameter-level meaning beyond what's in the schema; the only extra hint ('Use the ready-to-post block...') is already present in the schema for commentText. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose with specific verbs ('post, add, or save') and a specific resource ('review comment to an ADO Pull Request'). It distinguishes itself from the sibling tool `ado_post_comment` by focusing on PR review comments and explicitly referencing the prior analysis 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?

The description gives explicit when-to-use guidance: 'WHEN: user explicitly asks...' and 'PRIORITY TRIGGER: call AFTER ado_analyze_pr_impact...' with example phrases. It also provides a recommended workflow with steps and a warning to ask for confirmation, fully clarifying usage 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 include readOnlyHint=true, and the description reinforces this by framing all actions as scanning, listing, detecting, and computing. It adds meaningful context beyond annotations: it detects object conflicts and branch chains, computes merge order, and requires Code: Read scope. No contradictions exist.

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, front-loaded with the tool's purpose, and breaks down details into bullet points and sections. Every sentence contributes value—purpose, method, outputs, triggers, and requirements—without verbose filler.

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

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

Despite lacking an output schema, the description thoroughly enumerates what the agent can expect: per-PR object table, conflict matrix, dependency graph summary, and ordered merge sequence. It also covers operational requirements and trigger scenarios, making it self-contained 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?

The input schema already provides complete descriptions for all 5 parameters (100% coverage), so the baseline is 3. The description does not add parameter-specific semantics beyond what the schema provides, but it does mention environment variables (DEVOPS_ORG_URL/DEVOPS_PAT) that are not in the schema. This is adequate but not exceptional.

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 unambiguously states the tool scans multiple Pull Requests and builds a cross-PR dependency graph based on shared X++/AOT objects and branch chain relationships. It enumerates specific outputs and trigger phrases, making it clearly distinct from siblings like ado_list_prs or ado_analyze_pr_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?

Clear usage context is provided through trigger phrases ('PR dependencies', 'conflits entre PR', etc.) and the multi-PR scope. It also states the prerequisite of DEVOPS_ORG_URL + DEVOPS_PAT. However, it does not explicitly contrast with single-PR alternatives like ado_analyze_pr_impact, so it lacks explicit 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?

Despite having readOnlyHint annotation, the description adds significant behavioral context beyond annotations: 'Returns max 50 work items with ID, title, type, state, priority, area, assigned-to,' 'Requires DEVOPS_ORG_URL + DEVOPS_PAT env vars,' and 'Use '*' with filters only.' These details inform the agent about limits, prerequisites, and query syntax nuances. No contradiction with annotations.

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

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

The description is long but densely informative, with clear sections: scope, trigger keywords, exclusions, shortcuts, return behavior, and prerequisites. Each sentence adds value, but the length is near the upper bound for a tool description. It is structured effectively, so a 4 is appropriate.

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

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

For a read-only query tool with no output schema, the description provides essential context: return field list, result limit, environment variable requirements, and usage patterns. It lacks error handling or edge-case behavior, but given the tool's simplicity and rich schema, it is adequately complete. A 4 reflects minor gaps such as missing pagination or error scenarios.

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

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

The input schema covers all 11 parameters with descriptions (100% coverage), so baseline is 3. The description adds value by explaining the 'query' parameter's syntax options: shortcuts ('bugs', 'my bugs'), WIQL statements, free-text title search, and the wildcard '*' usage. It also mentions shortcut behaviors, which is beyond schema. This warrants a 4.

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: 'Query Work Items (Bugs, Tasks, FDDs, User Stories, CRs) in Azure DevOps.' It uses a specific verb ('Query'), identifies the resource ('Work Items'), and distinguishes from siblings through explicit exclusions and alternative tools. The 'AZURE DEVOPS ONLY' prefix further clarifies 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?

The description provides explicit usage triggers: 'PRIORITY TRIGGER: use this tool when the user mentions...' with a comprehensive keyword list. It also gives clear when-not-to-use guidance and alternative tools: 'NEVER use this tool for: D365 labels... For labels -> use search_labels.' This is exemplary usage guidance.

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

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

Goes far beyond the readOnlyHint annotation: discloses per-format return behavior (.xlsx returns sheet names + markdown table, .docx extracted markdown, images as base64 data URI), size limits (max 25 MB, images 4 MB), unsupported formats (PDF, pptx) with fallback behavior, and env var requirements. No contradictions with annotations.

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

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

The description is long but densely informative, with a clear front-loaded purpose statement followed by structured usage scenarios, triggers, format-specific behavior, and requirements. Every sentence earns its place; the complexity of the tool justifies the length, though it could be slightly more compact.

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 thoroughly covers return formats, size limits, unsupported cases, and discovery workflow. It anticipates the user's needs (how to find attachment names, what to expect per format) and leaves no major gaps for a tool of this complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying that fileName must be the exact name from ado_analyze_workitem and that sheetName applies only to spreadsheet attachments. It also notes case-insensitivity, adding practical value beyond the schema.

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

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

Description opens with a specific verb+resource: 'Reads the ACTUAL CONTENT of a file attached to a work item.' It explicitly lists supported file types and distinguishes itself from sibling tools (e.g., ado_analyze_workitem) by focusing on attachment content. The 'AZURE DEVOPS ONLY' prefix further scopes the tool.

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

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

Provides explicit WHEN conditions (work item has an Excel/Word attachment with requirements, mappings, etc.), triggers ('read the attachment', 'open the excel file'), and even names the companion tool to call first (ado_analyze_workitem) to discover attachment file names. This gives clear guidance on when to use vs. 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 already declare readOnlyHint and idempotentHint, and the description reinforces this by framing the tool as returning a review without side effects. It discloses the need for specific environment variables, PAT scope, and an XRef index, and clarifies that it does not post comments but must be combined with ado_post_pr_comment. This adds meaningful behavioral context beyond the annotations.

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

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

The description is well-structured, starting with the 'WHEN' clause and then covering outputs, triggers, requirements, and next steps. It is somewhat long due to the trigger phrase list, but every element serves a purpose. The front-loading makes it easy to scan.

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

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

Given no output schema, the description thoroughly explains what the tool returns (structured code review with blast radius, violations, performance, impact). It also covers prerequisites and usage guidance. For a complex D365-specific tool, this is highly complete and leaves little ambiguity for an AI agent.

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

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

Schema description coverage is 100%, with each parameter (prId, project, repositoryId, maxDeepAnalysis) already documented in the schema. The description adds a high-level explanation of the analysis process but does not add parameter-specific semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: reviewing a PR that modifies X++ code or AOT objects and returning a structured code review. It lists specific outputs (blast radius, best-practice violations, performance issues, impact severity) and distinguishes itself from generic PR tools by emphasizing D365-specific insights.

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

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

Usage context is explicit with a 'WHEN' clause and trigger phrases, plus prerequisites (DEVOPS_ORG_URL, DEVOPS_PAT, XRef index). It also recommends combining with ado_post_pr_comment for posting findings. However, it does not explicitly name alternative tools for non-X++ PR reviews, leaving the exclusion implied.

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

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

With no annotations, the description carries the burden of disclosing behavioral traits. It reveals a critical safety requirement (confirmation before calling), and a permission requirement (DEVOPS_PAT with Work Items: Write). It does not describe failure modes, reversibility, or return format, but covers the most important operational constraints.

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

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

The description is four sentences, front-loaded with the primary action. It efficiently includes examples, triggers, a safety instruction, and permission requirements without being verbose. Minor redundancy with the schema prevents a perfect score.

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

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

For a mutation tool with a well-specified schema and no output schema, the description covers the essential aspects: purpose, field naming conventions, examples, permission, and confirmation. It doesn't mention error handling or return values, but these are less critical for an update operation. The description feels complete enough for an agent to use it correctly.

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

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

Schema coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some extra context (e.g., using HTML for Description), but largely repeats information from the schema. It doesn't significantly enhance understanding beyond the structured field descriptions.

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

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

The description clearly states the verb 'Update' and the resource 'existing Azure DevOps Work Item', with scope 'one or more fields'. It distinguishes from sibling tools like ado_create_task or ado_query_workitems by focusing on updating fields, and gives concrete examples of standard and custom fields.

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

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

It provides explicit behavioral guidelines: always show changes and ask for confirmation, and requires a PAT with Write permission. It also lists example triggers to signal when the tool is appropriate. However, it does not explicitly contrast with alternative tools or state when not to use it.

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

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

Beyond the destructiveHint annotation, the description explains the full-body replacement, no merge/append behavior, automatic ETag handling for concurrent edits, and required env vars with PAT Wiki Read/Write scope. This is substantive added context that helps the agent predict side effects.

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

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

The description is front-loaded with the scope warning, then the action, followed by essential warnings and prerequisites. Every sentence adds important information without redundancy, making it efficient and easy to parse.

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

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

For a write operation with no output schema, the description covers purpose, usage, behavioral nuances, and prerequisites thoroughly. It doesn't explicitly describe success/error return values, but that is less critical for a create/replace tool and the essential invocation details are present.

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

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

Schema coverage is 100% and the param descriptions are already detailed. The tool description adds some extra context (e.g., parent pages auto-created) but doesn't provide additional parameter-level syntax or format details, so the baseline 3 is appropriate.

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

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

The description uses a specific verb+resource pair ('Create a new wiki page, or OVERWRITE an existing one') and adds the critical detail that it replaces the entire body rather than merging. It clearly distinguishes from sibling wiki tools like get, delete, and list.

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

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

Explicit guidance is provided: 'ALWAYS call ado_wiki_get_page first if you intend to edit (not replace) an existing page's content.' It also clarifies the tool's non-merge behavior, giving the agent a clear decision rule for when to use this vs. an alternative.

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

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

The annotations provide destructiveHint=true, and the description adds valuable context by explaining that sub-pages are also deleted and by specifying exact environment variable requirements plus PAT scope. This goes beyond the annotation, though it does not mention irreversibility or error behavior.

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

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

The description is two concise sentences that front-load the purpose and add critical caveats. Every sentence earns its place without redundancy.

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

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

For a delete operation, the description covers the main purpose, cascading deletion, required environment variables, and access scope. It could additionally mention irreversibility or behavior when the page does not exist, but overall it is sufficiently complete for the tool's complexity.

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

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

The input schema already has 100% coverage with descriptive parameter definitions. The tool description itself adds no extra parameter-specific meaning, so it does not exceed the baseline provided by the schema.

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

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

The description clearly states the tool deletes a wiki page with the specific verb 'Delete' and specifies the resource. It distinguishes itself from sibling tools like ado_wiki_get_page, ado_wiki_create_or_update_page, and ado_wiki_list by focusing exclusively on deletion.

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

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

The description provides clear context for use, including the 'AZURE DEVOPS ONLY' restriction, the behavior of deleting sub-pages, and required environment variables. It implicitly signals it is for deletion scenarios, but does not explicitly name alternative tools or state when not to use it.

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

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

Annotations declare readOnlyHint=true, so the safe read nature is already known. The description adds useful context: requires DEVOPS_ORG_URL + DEVOPS_PAT env vars and clarifies the read scope includes immediate sub-page paths, which goes beyond the annotation.

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

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

The description is two sentences, front-loaded with the Azure DevOps scope and purpose. Every sentence serves a purpose: scope, action, syntax example, and env var requirements. No redundant wording.

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

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

For a read-only tool with full schema coverage and annotations, the description is sufficiently complete. It specifies scope, requirements, and path syntax. The only gap is not describing return format, but the absence of an output schema is not critical for a simple read operation.

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

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

The input schema has 100% coverage with descriptive text and examples. The description essentially repeats the path example from the schema without adding new parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool reads wiki page content and immediate sub-page paths. It uses a specific verb (Read) and resource (wiki page), and distinguishes itself from sibling write (create/update/delete) and list tools by the action and 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 clear context for when to use: Azure DevOps only, requires specific env vars, and describes path syntax. However, it does not explicitly mention alternatives (e.g., ado_wiki_list) or exclusions.

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

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

Annotations already declare readOnlyHint, so the description adds useful context by specifying environment requirements (DEVOPS_ORG_URL + DEVOPS_PAT), scope limitation to Azure DevOps, and the inclusion of both project wiki and code-as-wiki repos. It does not contradict annotations.

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

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

Two sentences, front-loaded with scope and purpose, followed by usage guidance and prerequisite environment variables. Every sentence adds value with no wasted words.

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

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

For a simple list operation with one optional parameter and a readOnly annotation, the description covers purpose, usage, and prerequisites. No output schema exists, but the output (list of wikis) is self-evident from the tool's purpose.

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

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

Schema description coverage is 100% for the single optional parameter, which already documents that it falls back to DEVOPS_PROJECT env var. The description adds no additional parameter details, so the baseline of 3 is appropriate.

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

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

Specific verb 'List' with resource 'wikis in a project', including the nuance of 'project wiki plus any published code-as-wiki repos'. It clearly distinguishes from sibling wiki page tools by focusing on listing rather than reading/writing/deleting a particular page.

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

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

Explicitly instructs 'Use this FIRST when the user doesn't know the wiki's exact name/id, or to confirm which wiki to target before reading/writing a page.' This provides direct usage context and contrasts with sibling operations, giving clear when-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?

The description adds significant detail beyond the readOnlyHint and idempotentHint annotations: it specifies the analysis scope (CoC targets, event handlers, extensions, hard-coded refs), what it detects (removed objects, signature changes, deprecated APIs), and the output ('prioritized risk report with fix recommendations'). No contradiction.

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

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

The description is fairly long but well-structured: it leads with WHEN, then explains the analysis, lists examples, and states output and requirements. Every sentence conveys useful information, though the trigger list could be trimmed without loss of essential 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?

Given the tool's complexity (0 params, no output schema), the description is remarkably complete: it covers use case, triggers, prerequisite, analysis depth, output format (prioritized risk report), and recommendations. It adequately prepares an agent to select and invoke the tool correctly.

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

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

With 0 parameters, the schema is empty, and the baseline is 4. The description adds value by mentioning the prerequisite 'Requires D365_CUSTOM_MODEL_PATH', which is not in the schema. This helps the agent understand an environmental dependency.

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

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

The description states a specific action ('Analyze upgrade risk'), a specific resource ('custom D365 F&O model'), and the approach (cross-referencing custom code against the standard codebase). It clearly distinguishes itself from siblings like find_change_impact by focusing on the upgrade scenario.

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

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

The description provides an explicit 'WHEN' clause (upgrading D365 F&O or applying a Microsoft update) and includes trigger phrases. However, it does not mention when not to use it or name alternatives, so it stops short of a perfect score.

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

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

With no annotations provided, the description carries the transparency burden. It discloses the key behavior: it removes a cached connection, is session-scoped, and is tied to the setter. It does not detail idempotency, error behavior, or consequences for subsequent queries, but the statement 'cached for the current session' gives important context beyond the tool name.

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

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

The description is a single, grammatically clear sentence that front-loads the verb 'Removes' and includes the essential details (what is removed, scope, and relationship to setter). There is no superfluous 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 simple tool with no parameters or output schema, the description is largely complete: it states the action, scope, and pairing with set_connection. It lacks explicit mention of return value or edge cases, but for a clear/remove operation of this simplicity, the information provided is sufficient.

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

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

The tool has zero parameters (schema coverage 100% with no properties). Per rubric, the baseline is 4. The description adds no parameter detail because there are none to explain, and no parameter-related information is needed.

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 action: 'Removes the Application Insights connection cached for the current session.' It names the specific resource (Application Insights connection), the scope (current session), and links to the companion setter (appinsights_set_connection), distinguishing it from siblings like appinsights_query and appinsights_set_connection.

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

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

The description implies usage: call this when you want to clear the cached connection for the current session, particularly after using appinsights_set_connection. It provides clear context and implicitly differentiates from alternatives by referencing the paired setter, though it does not explicitly state 'when not to use' or name 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?

No annotations are present, so the description carries the full burden. It discloses the tool runs KQL queries, assembles a report, conditions on data availability ('only rendered if the workspace actually has data'), and requires a pre-configured connection. It could be more explicit about being read-only, but the diagnostic nature is clear from context.

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

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

The description is well-structured, front-loaded with 'WHEN', and uses a numbered list to clearly enumerate report sections. Every sentence contributes value—prerequisites, data source, output composition, and conditional rendering—without fluff.

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

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

Given no annotations and no output schema, the description is remarkably complete: it covers purpose, trigger scenarios, prerequisites, what the report includes, and data-dependent behavior. It leaves no major gaps for an agent to mis-invoke 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?

Input schema covers 100% of parameters with descriptions and defaults, so baseline is 3. The description adds slight semantic context (e.g., minDurationMs relates to flagging 'slow' events, lookbackHours implies time window), but this mostly reinforces schema info without going much beyond it.

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

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

The description clearly states the tool's purpose: 'diagnose slowness' using Application Insights telemetry. It lists specific report sections (X++ exception hotspots, custom telemetry events, slow web requests) and differentiates it from generic queries like appinsights_query by noting it runs 'canned KQL queries' and assembles a combined report.

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?

Starts with 'WHEN: user wants to understand/deduce why a D365 F&O environment feels slow' and provides explicit prerequisites ('Requires the connection to be configured first via appinsights_set_connection'). It also mentions that no trace file upload is needed, distinguishing from alternatives, and lists trigger phrases for clarity.

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

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

With no annotations provided, the description carries the full burden. It clearly discloses the read-only nature ('the query language has no mutation operators') and the connection prerequisite. It doesn't detail error handling or return format, but the read-only safety aspect is the most critical behavioral trait and is explicitly stated.

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

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

The description is concise and well-structured: purpose, prerequisite, usage differentiation, and trigger phrases. Every sentence earns its place, and trigger phrases are especially useful for AI agent selection without adding bloat.

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

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

Despite no annotations and no output schema, the description provides sufficient context: what the tool does, the environment it targets, the schema to use, the prerequisite, and the sibling alternative. The parameter details are well-covered in the schema, so the description need not repeat them.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the standard App Insights schema tables (requests, dependencies, exceptions, etc.), which directly enriches the semantics of the 'kql' parameter. This goes beyond simply repeating schema field names.

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

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

The description opens with a specific verb+resource: 'Run a raw KQL (Kusto) query against the D365FO environment's Application Insights / Log Analytics workspace.' It also explicitly differentiates from the sibling appinsights_diagnose_slowness by advising to prefer that tool for ready-made reports and use this one for custom queries.

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

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

Provides explicit when-to-use guidance: 'Prefer appinsights_diagnose_slowness for a ready-made... use this tool for anything more specific/custom.' It also states the prerequisite of configuring the connection via appinsights_set_connection or server env vars, and lists trigger phrases 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It richly discloses security and session behavior: client secret encrypted in memory with AES-256-GCM, never written to disk, never echoed back, session-scoped, automatic use by dependent tools, and disabled in locked server mode. It also explains the read-only role requirement, which is critical for safe usage.

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 detailed for a security-sensitive setup tool. It is front-loaded with the main purpose, then structured into 'HOW TO GET THE VALUES' and a locked-server note. Every sentence adds valuable information—there is no fluff or redundancy. The length is justified by the complexity of the task.

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

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

Given the tool's complexity, the description is remarkably complete. It covers the intent, session scope, security mechanisms, dependent tools, prerequisites (Entra ID role), how to obtain each parameter, and the locked-server deployment behavior. No output schema exists, and the description doesn't need to explain return values for a setter tool. The only minor omission is what happens if a connection already exists, but this does not significantly impact completeness.

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?

Although schema description coverage is 100%, the description adds significant meaning beyond the schema. It clarifies that workspaceId is the Log Analytics workspace ID (GUID) and not the App Insights app id, provides a detailed 'HOW TO GET THE VALUES' section including Azure Portal navigation, explains the required Entra ID roles for tenantId/clientId/clientSecret, and clarifies that the secret is encrypted and never persisted. This goes well beyond the schema's basic property descriptions.

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

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

The description clearly states the tool's purpose: 'Securely register the D365 F&O environment's Application Insights / Log Analytics connection for the CURRENT session.' It uses a specific verb (register) and resource (telemetry connection), and distinguishes from siblings by noting that appinsights_query and appinsights_diagnose_slowness use this connection automatically, and appinsights_clear_connection removes it.

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

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

The description provides clear usage context: it should be called before appinsights_query or appinsights_diagnose_slowness, and it remains active until expiry or explicit clear. It also gives an explicit exclusion: in a locked server deployment (APPINSIGHTS_LOCK_SERVER_CONFIG=true) the tool is disabled. However, it does not explicitly discuss alternatives like d365fo_set_connection or contrast with clear_connection beyond the auto-use note.

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

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

Goes well beyond the readOnlyHint annotation by disclosing parallel execution, the 6-query cap, full chunk loading of results, and the resulting follow-up constraint. This gives the agent critical behavioral context for invocation and downstream actions.

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

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

The description is longer than average but every sentence earns its place, with a clear WHEN/INSTEAD/results/warning structure. The trigger phrase list is somewhat redundant but reinforces usage guidance without being bloated.

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

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

For a parallel search tool with well-defined schema, the description covers the essential context: equivalence to search_d365_code, full-loading effects, maximum query count, and the explicit warning not to call get_object_details. No output schema exists, but the description adequately conveys 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?

Schema coverage is 100%, so parameters are already well-documented. The description adds value by explaining that each line of the queries parameter becomes one parallel search and that topObjects yields fully loaded objects, clarifying how the parameters map to execution behavior.

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 runs multiple D365 object/concept searches in parallel, and explicitly distinguishes it from the sibling search_d365_code and get_object_details. The verb+resource+scope are specific and unambiguous.

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

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

Provides explicit when-to-use guidance ('WHEN: you need context on multiple D365 objects'), explicit alternative ('Use INSTEAD of multiple sequential search_d365_code calls'), and even exclusions ('Do NOT follow up with get_object_details'). Trigger phrases further aid agent selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful behavioral context by enumerating what is compared (fields, methods, signatures), which goes beyond the bare schema. No contradictions exist.

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 exactly two sentences, front-loaded with the core purpose and followed by a useful use-case note. Every word earns its place; there is no filler or redundancy.

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

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

The tool is simple with only two parameters and no output schema. The description covers purpose, what is compared, and common use cases. It does not mention the output format, but for this tool the output is inherently a side-by-side comparison, making the description sufficient.

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

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

Schema description coverage is 100% with both parameters (objectNameA, objectNameB) having clear descriptions and examples. The tool description does not add additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Compare two D365 F&O objects side-by-side' and specifies the aspects compared ('fields, methods, signatures'). This specific verb+resource+scope distinguishes it from siblings like diff_model_versions (which compares model versions) and get_object_details (which retrieves details for a single object).

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

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

The description provides clear when-to-use guidance: 'Handy when investigating differences between standard and a customisation, or between two similar tables.' It gives concrete scenarios but does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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

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

Beyond the readOnlyHint annotation, the description explicitly states it 'never writes to the filesystem, never mutates external state, and is safe to expose from the cloud MCP.' It also discloses that the calling client is responsible for writing the result, which is critical behavioral context. This fully satisfies the transparency requirement.

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

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

The description is long, but the length is justified by the 18 supported aotTypes. The structure is clear: a concise intro followed by organized per-type sections. Each line serves a purpose, though the density could be overwhelming; a shorter summary might improve quick scanning.

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

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

For a tool with no output schema, the description adequately explains the output (XML + file path) and covers input options exhaustively. It lacks details on error handling or exact response format, but the core usage is fully documented. The enrichment behavior adds completeness but is conditional.

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 provides 100% coverage with descriptions for the 3 parameters, the description adds a massive per-aotType option matrix, giving meaning to every possible 'options' key (e.g., 'tableGroup', 'cacheLookup', 'fields' formats). This is far beyond the schema's generic example and provides crucial semantic detail for correct usage.

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

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

The opening line states the exact action and scope: 'Generate a complete, ready-to-deploy D365 F&O AOT XML scaffold for any object type.' It also clarifies the tool's dual output (XML + file path) and responsibility boundary, which distinguishes it from sibling generators like generate_query or generate_data_entity.

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

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

The description provides clear context for when to use the tool: whenever an AOT object scaffold is needed, with client-side write responsibility. It also notes a conditional enrichment when the knowledge base is available. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It explains what is removed (cached connection) and its scope (current session), but does not mention side effects (e.g., whether it's safe to call with no active connection) or idempotency. For a simple state-clearing tool, this is adequate but lacks depth.

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

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

The description is a single, clear sentence that conveys all essential information without waste. It is perfectly front-loaded with the action and object.

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

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

For a zero-parameter, no-output-schema tool that simply resets a cached connection, the description is fully complete. It names the tool it pairs with and the exact thing it clears, leaving no ambiguity.

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

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

The tool has zero parameters, so the description need not add parameter semantics. The baseline of 4 applies, and the description adds no unnecessary parameter details.

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

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

The description clearly states the action ('Removes') and the specific resource ('D365 F&O connection cached for the current session'). It names the paired setter tool (d365fo_set_connection), which distinguishes it from similar clear tools like appinsights_clear_connection.

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

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

Use is implied for clearing a D365 F&O connection established by d365fo_set_connection. It doesn't explicitly state when not to use it or mention alternatives, but the context is clear and the sibling setter name provides a mental trigger for when this tool is relevant.

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

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

With no annotations, the description takes full responsibility for transparency. It discloses that the client secret is encrypted in memory (AES-256-GCM), never written to disk or echoed back, that the connection automatically applies to odata_* and dmf_* tools, has an expiration/TTL, and is disabled under locked server configuration. This is comprehensive behavioral context beyond what the schema provides.

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

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

The description is concise and well-structured. It leads with the primary purpose, then explains security and usage details, and ends with the disabled-lockdown caveat. Every sentence provides meaningful information; there is no redundant or filler content.

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

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

The description covers the tool's role in the broader tool ecosystem (how odata_* and dmf_* tools use it), the security model, the TTL behavior, and the locked-server exception. It does not mention return values or error handling, but for a setter tool with no output schema this is a minor gap. Overall, it's well contextualized.

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

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

The input schema provides 100% description coverage for all 5 parameters, each with clear descriptions (e.g., baseUrl includes an example and 'https only', clientSecret notes encryption). The description adds general context about URL + Entra app-registration credentials and the client secret's encryption, but this mostly restates schema information. Since schema coverage is high, the baseline of 3 applies.

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

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

The description clearly states the tool's purpose: 'Securely register the D365 F&O connection... for the CURRENT session.' It uses a specific verb ('register'), identifies the resource (D365 F&O connection), and sets the scope (session). It also distinguishes from related tools by noting it feeds all odata_* and dmf_* tools and that d365fo_clear_connection resets it.

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

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

The description provides explicit usage guidance: 'Use this instead of resending the secret on every call.' It also explains when the tool is not applicable, stating it is disabled in locked server deployments (D365FO_LOCK_SERVER_CONFIG=true) and that server credentials are used instead. This clearly informs when to choose 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?

The annotation declares readOnlyHint=true and idempotentHint=true, but the description says 'Auto-fixing requires D365_CUSTOM_MODEL_PATH (custom code only)', implying the tool can modify code when that path is set. This contradicts the readOnlyHint annotation. No other behavioral details are provided, and the contradiction is significant.

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

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

The description is three sentences: purpose with concrete checks, output format, and usage guidance. It is front-loaded with the core functionality and every sentence contributes meaningful information without redundancy.

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

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

For a read-only profiling tool with a well-described schema, the description covers purpose, checks, output, and usage. However, the ambiguous auto-fixing note creates a contradiction with annotations, which detracts from completeness and could confuse the agent.

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

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

Schema description coverage is 100%, so the schema already explains objectName and methodName. The description does not add additional parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Profile' and identifies the resource as 'an X++ object', then enumerates precise performance patterns (N+1 queries, queries in loops, missing field lists, row-by-row inserts/updates, missing firstOnly). It also distinguishes itself from validate_best_practices by targeting performance specifically.

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

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

It explicitly states when to use: 'Only call when performance is explicitly the concern'. It also names the alternative for general quality: 'for general quality use validate_best_practices'. This meets the when/when-not/alternative criterion.

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?

Annotation Contradiction. The tool is marked readOnlyHint=true, but the description instructs using 'save_baseline', which writes an output file (as clarified in the schema: 'output path for the baseline file'). This is a write operation and contradicts the read-only hint, misleading the agent about 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?

Two sentences, front-loaded with the main purpose, followed by a brief usage instruction. Every word earns its place with no fluff.

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

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

The description explains the primary 'compare' workflow but omits the 'compare_caches' action entirely, which is present in the schema. Combined with the annotation contradiction, the description is not fully complete for a tool with multiple modes and a potential side effect.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds workflow context for action ordering and mentions path1 depending on action, but most parameter meaning is already in the schema. No significant new semantics added.

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 function: 'Compare two D365 F&O KB snapshots to produce a changelog (added/removed/modified objects)'. It specifies the resource (D365 F&O KB snapshots) and output, differentiating it from sibling tools like compare_objects by focusing on KB snapshot versions.

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 workflow guidance: 'Use action save_baseline once, then compare between two snapshots.' This tells the agent how to sequence operations, though it does not mention alternatives or when-not-to-use the tool relative to siblings. It gives clear context for the intended 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?

Annotations only include readOnlyHint:false, and the description adds that each action forwards to the same implementation with identical behavior and validation. It doesn't disclose side effects, permission requirements, or return behavior beyond what parameter descriptions already offer, though no contradictions exist.

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

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

The description is long but necessarily so for covering 5 actions. It is well-structured with an intro sentence and a clean action-by-action breakdown. Every sentence contributes useful information, though it could be tightened slightly.

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

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

The description comprehensively covers actions and parameters, but with no output schema, it fails to state what each action returns (e.g., executionId, status, etc.). This is a notable gap for a dispatcher tool, even though the link to dedicated tools partially compensates.

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

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

While schema description coverage is 100%, the description significantly enhances parameter understanding by grouping parameters per action (import, create_project, apply_filter, export, status) and indicating optionality with '?'. This mapping is not present in the schema alone and greatly clarifies which parameters are relevant for each action.

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 is a consolidated one-entry-point tool for all 5 DMF operations, explicitly listing each action and its corresponding dedicated tool. This distinguishes it from sibling tools while being very specific about its purpose.

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

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

The description explains the consolidating purpose and notes that dedicated tools remain available unchanged, implying when to use this unified schema vs the individual tools. However, it does not explicitly state exclusion criteria or scenarios where the dedicated tools would be preferred.

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

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

The description discloses technical behavior well beyond the annotations: 'The kernel builds the packed query (custom GenerateQueryData action), the container envelope is stripped on the QueryRun.pack() signature, and the inner blob is PATCHed onto DataManagementDefinitionGroupDetails.QueryData.' This explains how the filter is applied and that it modifies the project definition. It also notes the side effect that child rows are not auto-filtered. None of this contradicts the annotations (idempotentHint=true, destructiveHint=false).

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

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

The description is longer but every sentence contributes actionable information. It front-loads the core purpose and then adds constraints, examples, and a critical warning. The structure is logical: purpose, mechanics, limitations, and requirement. It earns a 4 rather than 5 because it could be slightly trimmed without losing value, but it is not verbose or redundant.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It explains the purpose, the exact mechanics, the single‑field limitation, the parent/child caveat, the prerequisite custom action, and the wildcard behavior. It also provides examples for field names and values. There is no ambiguous behavior left unaddressed for a typical AI agent invocation.

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

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

The input schema already covers all parameters with descriptions, so the baseline is 3. The description adds extra semantics by explaining that only a single field/value combination is supported per call, that wildcards are passed through (e.g., '1001*'), and that entityRowName refers to the project line label. This enriches the parameter meaning beyond the schema definitions, such as clarifying the relationship between parameters.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Apply a single-field value filter to ONE entity row of an existing DMF project, so the export only contains the matching records.' It also distinguishes itself from sibling DMF tools by emphasizing it filters an existing project rather than creating or exporting. The phrase 'Works for ANY entity and ANY field' further clarifies the 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?

The description provides clear when-to-use context: 'only a single field = single value per call (call once per entity row)' and 'Works for ANY entity and ANY field.' It also gives important exclusions and requirements: 'filtering a parent does NOT auto-filter child rows' and 'Requires the custom GenerateQueryData action in the environment.' While it doesn't name alternative tools explicitly, it offers sufficient guidance on limitations and prerequisites.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false. The description adds behavioral details: POSTs to DataManagementDefinitionGroups and DataManagementDefinitionGroupDetails with AutoGenerateMapping=Yes, reuses existing projects, skips existing entities, and eliminates X++ customizations. No contradiction.

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

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

The description is a dense paragraph covering purpose, mechanism, idempotency, and next steps. All sentences contribute useful information; however, it could be slightly condensed without losing meaning.

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

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

The description explains the tool's full role: creation mechanics, idempotence, prerequisites, and connection to downstream tools. It doesn't specify return values, but no output schema exists and that's not critical for a creation tool. It covers the operation well.

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

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

Schema covers all parameters with descriptions. The description adds semantic value by requiring sourceName to be an existing format and by explaining that entities already present are skipped, which informs the entities parameter. The operationType default is clear. Overall, it enriches beyond the schema.

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

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

The description uses a specific verb 'Create (or extend)' with a clear resource 'DMF data project -- EXPORT or IMPORT'. It distinguishes from sibling tools like dmf_export_package and dmf_import_file by scoping its role to project definition.

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

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

It provides clear context: create the project first, then run with dmf_export_package for exports. It doesn't explicitly mention dmf_import_file or alternatives, but the workflow is clear. It also mentions 'Provide an EXISTING DMF source data format name' as a prerequisite. However, it lacks explicit '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?

No annotations are provided, so the description carries the full burden. It explains the prerequisite and indicates the tool waits for completion ('when complete'), but it does not disclose potential side effects of reExecute, authentication needs, rate limits, or what happens on failure. These gaps are significant for a potentially long-running action with no structured safety hints.

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

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

Three sentences covering purpose, prerequisite, and alternative. Every sentence earns its place with no redundant or filler content. The critical note is clearly separated and front-loaded.

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

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

For a complex tool with no output schema and no annotations, the description covers the core purpose, the key prerequisite, and the primary alternative. It mentions the download URL as the return value and implies polling behavior via 'when complete'. It does not explicitly describe the polling mechanism, but the parameter descriptions cover timeout and re-execution, so the description is reasonably complete for invoking 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?

The schema already provides 100% coverage with clear descriptions for all five parameters. The description adds minor context about definitionGroupId needing to exist and packageName derivation, but these are already implied by the schema. It does not substantially enhance parameter understanding beyond the schema.

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

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

The description clearly states the action ('Trigger a bulk export'), the resource ('Data Management package REST API'), and the outcome ('return the download URL'). It also distinguishes from sibling tools by naming odata_export_entity for ad-hoc exports and dmf_create_data_project for project creation.

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

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

Explicitly provides usage context: a prerequisite (the DMF export project must exist), a fallback creation tool (dmf_create_data_project), and an alternative for ad-hoc exports (odata_export_entity). This gives clear when-to-use guidance.

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

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

With no annotations provided, the description carries the transparency burden. It discloses that the tool is a polling status check (read-only implied), enumerates possible return states (e.g., Succeeded, Failed), and reveals that completed exports include a download URL. This is useful behavioral context beyond the schema, though it doesn't discuss rate limits or potential long-running operations.

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

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

Two concise sentences front-load the core purpose, then add status examples and the export download URL behavior. Every word adds value with no redundancy or filler.

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

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

For a low-complexity tool with one parameter and no output schema, the description sufficiently explains what the tool returns (status and download URL). It could mention non-destructive behavior or error handling, but the 'Poll' wording and status list make the tool's behavior adequately complete.

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

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

The schema already provides 100% coverage for the single parameter, including its source ('returned by dmf_import_file or dmf_export_package'). The tool description repeats 'by its executionId' without adding further semantic nuance. Baseline 3 is appropriate as the description doesn't materially enhance parameter understanding.

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

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

The description uses a specific verb ('Poll') and resource ('status of a DMF import/export execution'), clearly distinguishing it from sibling tools like dmf_import_file and dmf_export_package which initiate operations. It also specifies the key parameter (executionId) and gives concrete status examples.

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

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

The description implies usage after an import/export by referencing executionId returned by dmf_import_file or dmf_export_package, and mentions 'Poll' indicating repeated calls. It lacks explicit 'when not to use' statements, but the context is clear enough for correct selection among DMF 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 annotations (destructiveHint, openWorldHint), the description discloses important behavioral details: it auto-creates the data project from the manifest, uploads to Azure blob, runs in batch, polls until completion, and returns final status plus an error-keys URL on failure. This gives the agent a strong mental model of the tool's side effects and asynchronous nature.

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

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

Every sentence earns its place: purpose, process, batch behavior, input modes, and entity resolution guidance. The description is front-loaded with the core purpose and contains no filler or repetition of schema fields.

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

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

Despite the lack of an output schema, the description covers the key aspects: what it does, how it works, side effects (auto-created project), asynchronous behavior, return value (status and error-keys URL), and input alternatives. It is sufficiently complete for a complex tool with 8 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?

With 100% schema description coverage, the baseline is 3. The description adds extra value by explicitly instructing to resolve entityName via find_entity_for_table and clarifying the filePath/csvContent mutual exclusion, which is helpful even though it partially echoes the schema.

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

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

The description clearly states the tool's function: 'Bulk-import a CSV file into a D365 F&O entity through the Data Management package REST API.' It uses a specific verb and resource, and the process details (builds package, uploads to blob, calls ImportFromPackage) further distinguish it from sibling tools like dmf_export_package.

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

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

It provides clear context on how to use the tool: 'Provide either filePath (a .csv on disk) or inline csvContent' and 'Resolve the entity name from the KB (find_entity_for_table) -- do not invent it.' However, it does not explicitly state when not to use this tool or name alternative tools for related operations (e.g., dmf_create_data_project), so it lacks exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the offline nature ('NO FO credentials required'), input constraints ('small files only'), and output behavior including downstream feed targets. It also explains a key transformation rule: autoGeneratedFields are 'removed so FO generates them.' This provides substantial transparency beyond a simple transform description, though it omits details on error handling and exact conditionalValues semantics.

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

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

The description is a single, well-structured paragraph with dense, purposeful sentences. Each segment—purpose, credential note, input methods, mapping spec, output routing, diagnostic flag—adds essential information without redundancy. Though lengthy, the complexity of the tool justifies every sentence, and the most critical information (purpose and input options) is front-loaded.

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

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

Given the tool's complexity (8 parameters, complex mapping spec, no output schema), the description is notably complete. It covers input alternatives, mapping capabilities, output formats and downstream integration, and the diagnostic listSheetsOnly mode. It lacks some edge-case details like error handling and size limits for sourceUrl/filePath, and the conditionalValues structure is only sketched, but an agent can reasonably select and invoke the tool correctly based on this description.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by elaborating on the mappingJson spec: it enumerates supported keys (sourceSheet, targetSheet, columnMappings, conditionalValues, staticValues, deduplicateOn, autoGeneratedFields) and gives a concrete example of the sheet-keyed autoGeneratedFields format. This goes beyond the schema's one-line description and helps the agent construct valid inputs.

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

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

The description opens with a specific action and outcome: 'Transform a multi-sheet Excel (.xlsx) into DMF-ready rows using a data-driven JSON mapping'. It also names the equivalent function (FO_TransformExcelForDMF) and clarifies it's an offline transform, distinguishing it from related import/export tools. The purpose is unambiguous and distinct from sibling tools.

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

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

The description gives clear usage context: 'NO FO credentials required (offline transform)' and 'Provide the workbook via ONE of: sourceUrl... filePath... or fileContentBase64 (inline upload, small files only)' tells the agent when and how to use it. It also provides downstream routing guidance ('Returns CSV (default, feed to dmf_import_file) or JSON (feed to odata_upsert_rows)') and a diagnostic mode. However, it doesn't explicitly contrast with sibling tools like dmf_create_data_project or dmf_import_file, which would have pushed it to a 5.

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

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

Annotations already provide `readOnlyHint: true`, which covers the safety profile. The description adds that output is 'plain business language' and free of X++/jargon, which is useful but does not go beyond this to discuss other behavioral traits such as response structure or data sources. It neither contradicts the annotations nor adds substantial behavioral depth.

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

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

The description is front-loaded with usage guidance and structured with labels like 'WHEN' and 'NOT'. However, the purpose is restated multiple times: the WHEN section and the WORKFLOW EXPLAINER line echo the same content, and the triggers list adds length. It is reasonably organized but contains redundancy.

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

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

Given the tool's moderate complexity, a single parameter, and a `readOnlyHint` annotation, the description covers the essential context: what the tool does, when to use it, its output tone, and how it differs from a sibling. It does not describe return format, but no output schema exists and the explanation-oriented behavior is conveyed clearly.

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

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

The input schema has 100% description coverage for the single parameter, including examples ('SalesTable', 'PurchTable', 'ALMDemandeAchatWorkflow'). The tool description does not add additional parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Explains') and a concrete resource ('D365 approval workflow'), and enumerates the exact aspects covered: who approves, what states exist, and what happens on approval/rejection. It also distinguishes itself from the sibling tool `get_object_details` by explicitly stating it is not for technical workflow class details.

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

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

The description provides explicit usage conditions prefixed with 'WHEN,' including example user intents, and an explicit exclusion: 'NOT for technical workflow class details -- use `get_object_details`.' It also lists trigger phrases to help the agent recognize when to invoke the tool.

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

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

Annotations include readOnlyHint=true, so the safe-read nature is already known. The description adds valuable behavioral context: parallel fan-out, RRF merging, the local server always being the primary source, and peer configuration via environment variable. It does not cover auth or rate limits, but with the annotation covering safety, this is solid.

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

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

The description is concise at three sentences, each earning its place. It opens with the primary action, follows with the use case, and ends with configuration details. No fluff, no repetition, and front-loaded for quick understanding.

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

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

The description covers the tool's purpose, when to use it, and how it is configured. However, with no output schema, it does not describe the return format or behavior on peer failures. Given the complexity, it's nearly complete but leaves a minor gap in expected output 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%, so the baseline is 3. The description does not add extra meaning to parameters like topK or peerApiKeys beyond what the schema already provides; it only mentions the env var for peer configuration, which relates to peerApiKeys but not directly. This is sufficient but not exceptional.

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 function: 'Fan-out search across multiple ALM XPP MCP server instances in parallel and merge results using Reciprocal Rank Fusion (RRF).' This specific verb+resource (fan-out search, merge) distinguishes it from sibling search tools like search_d365_code and batch_search, which operate on a single server or a single query.

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

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

The description provides clear usage context: 'Useful when D365 code is split across multiple organisations or knowledge bases (e.g. one per client, one standard KB).' This explains when to use it, but it does not explicitly mention when not to use it or name alternatives, stopping short of a 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds valuable context about the index requirement and fallback to vector-search. This goes beyond the annotation-provided safety profile without contradicting it.

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

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

The description is two sentences, front-loaded with the primary purpose and followed by the dependency and fallback note. Every sentence adds value with no redundancy.

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

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

Despite lacking an output schema, the description explains the breadth of the profile and the fallback behavior. It provides enough detail for an agent to understand the tool's scope, though a more explicit return format description would improve completeness.

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

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

The schema already documents all four parameters with 100% coverage. The description does not add extra meaning or examples for parameters, so it meets the baseline without exceeding it.

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

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

The description clearly states the tool produces a 'full cross-reference profile' for a class or method, listing specific components (callers, callees, inheritance, etc.). This distinguishes it from broader search tools like find_references, though it does not explicitly name alternatives.

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

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

The description implies usage through its detailed purpose but does not explicitly state when to prefer this over sister tools. It does provide a prerequisite (xref_index.json.gz) and a fallback behavior, which offers some contextual guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds meaningful behavioral context: requires XRef index (loaded from xref_index.json.gz), performs BFS up to 3 hops, and produces severity classifications. This goes beyond the annotations, though it doesn't detail all edge cases or output 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?

The description is information-dense and front-loaded with 'WHEN'. It includes trigger phrases, examples, and a combination tip. While slightly long, every sentence earns its place for a complex tool. The structure (WHEN → returns → requires → triggers → example → combination) is logical and efficient.

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

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

Given no output schema and the tool's complexity, the description covers the purpose, usage triggers, required setup (XRef), parameter semantics, and output content (blast-radius report details). It also addresses sibling differentiation and integration with other tools. This is a complete, self-sufficient description.

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

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

Schema coverage is 100% and both parameters have descriptions. The description adds crucial semantic value: 'Pass objectName='SalesLine' for table/class-level impact, or objectName='SalesLine.insert' for method-level impact.' It also clarifies maxDepth's role via 'BFS up to 3 hops' in the main text. This meaningfully augments the schema.

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

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

The description clearly states the tool's function: 'Returns a blast-radius report: direct callers, transitive dependents... severity classification.' The verb 'find change impact' is specific and the resource (X++ objects/methods) is explicit. It also distinguishes from sibling tools like find_callers and find_references by focusing on impact/blast radius.

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' guidance: 'about to modify an X++ object or method and need to understand what could break.' Includes trigger phrases and example usage (e.g., objectName='SalesLine'). Also suggests complementary tools: 'Combine with validate_best_practices / detect_performance_issues...' This gives clear context for when to use the tool versus alternatives.

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

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

Beyond the readOnly and idempotent annotations, the description discloses the tool's scanning behavior ('scans all indexed AxDataEntityView objects'), the return fields, and the conditional generation of a template when generateIfMissing=true. It clearly presents the generation side effect, which is important context even if the annotation suggests no persistent writes.

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

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

The description is longer than necessary, with a lengthy trigger list and some redundant explanations. It is front-loaded with the WHEN clause, which is good, but the overall structure could be more compact without losing essential information. It is still readable and organized, so it earns a middling score.

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

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

Despite lacking an output schema, the description sufficiently explains return values (entity name, public entity name, IsPublic status, key fields, data sources) and covers the main use case along with the generateIfMissing edge behavior. It gives an agent enough context to invoke the tool correctly and interpret results.

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

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

The schema descriptions cover all three parameters (100% coverage), providing details for tableName, maxResults, and generateIfMissing. The description repeats the generateIfMissing behavior but adds no extra semantic nuance beyond the schema. Therefore, the description provides no significant additional parameter meaning.

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

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

The description clearly states the tool's primary function: finding D365 F&O data entities that expose a given table for OData/DMF integrations. It uses a specific verb ('find') and resources ('data entities'), and includes an example query ('Which entity exposes SalesTable for OData?'). This distinguishes it from sibling tools like generate_data_entity, though it also mentions a generation capability as a secondary behavior.

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

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

The description provides an explicit WHEN clause ('developer needs to integrate via OData and wants to find the entity name for a given table') and lists trigger phrases that signal user intent. It does not explicitly name alternative tools to use instead, but the context is clear enough that an agent can identify the appropriate scenario.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds substantial behavioral context: it matches against a built-in error database, resolves label IDs, searches the indexed codebase, and returns root causes, resolutions, and source locations. This aligns with the read-only nature and enhances understanding beyond the annotations.

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

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

The description is long but well-structured with sections (WHEN, triggers, function, returns, special note). It includes extensive trigger examples that contribute to clarity, though some redundancy exists (e.g., repeated audience-type explanation). Overall, the structure helps scannability and the length is justified by the tool's complexity.

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

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

For a tool with no output schema, the description is remarkably complete: it covers when to use, what it does, what it returns, how to interact with sibling tools, and audience variations. It even provides a workflow for label resolution. This leaves minimal gaps for an agent to invoke it correctly.

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

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

While the schema already describes both parameters (100% coverage), the description adds semantic value by explaining that audienceType='business' produces a plain-language explanation for end users and providing concrete examples for errorOrSymptom. This enriches the parameter meaning beyond the schema.

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

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

The description explicitly states the tool's function: 'Find known D365 F&O error patterns matching an error message or symptoms description.' It also distinguishes itself from the sibling tool search_labels by noting label resolution and instructing to call search_labels first for label IDs.

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

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

The description provides a clear 'WHEN' section and lists specific triggers for both developer and business contexts. It explicitly names an alternative tool ('call search_labels first') and explains the audienceType parameter for choosing between developer and business explanations.

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 readOnlyHint already indicates safety, the description adds value by disclosing that it searches the knowledge base for specific SubscribesTo attribute patterns, which is beyond the annotation. This helps set expectations about the search scope and mechanism without contradicting the read-only hint.

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

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

The description is compact, front-loads the core purpose, and includes a concise WHEN list. The multilingual trigger phrases add a little length but are purposeful; the overall structure is 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 read-only search tool with three well-documented parameters and no output schema, the description covers what it does, how it searches, and when to use it. It does not describe the return format, but the simplicity and annotations make this adequate.

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 each parameter already has a description. The tool description reinforces eventName usage with an example but does not add significant semantic detail beyond the schema, matching the baseline for high schema coverage.

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

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

The description starts with 'Find all event handlers that subscribe to events on a D365 table or class,' which names the specific verb, resource, and target, clearly distinguishing it from siblings like find_references or find_callers. It further specifies the search pattern (SubscribesTo) making the purpose unmistakable.

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

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

Provides explicit WHEN guidance with natural-language trigger phrases in both English and French, plus advice to use eventName for narrowing. It does not mention alternatives or exclusions, but the usage context is clear and actionable without being misleading.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds meaningful behavioral context: it queries Azure DevOps Code Search in real-time for extensions not yet in the KB, implying potential network dependency and KB staleness. No contradiction with annotations; this is useful supplementary information.

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

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

Three concise sentences with no waste. The first sentence front-loads the core function with specifics, the second adds the live query behavior, and the third delivers an imperative usage directive. Every sentence earns its place.

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

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

The tool has moderate complexity with one parameter and no output schema. The description covers what the tool searches (KB + live Azure DevOps), what it finds (extensions, CoC, event handlers), and when to invoke it. It could describe return format, but the core context is sufficiently complete for an agent to call the tool correctly.

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

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

Schema coverage for the single parameter baseObjectName is 100%, with examples in the schema description. The tool description does not elaborate on parameter syntax or constraints beyond that, but since the schema already documents the parameter fully, the baseline of 3 is appropriate.

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

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

The description clearly states the tool finds all extension objects, CoC classes, and event handlers for a base object, enumerating specific extension types (AxClassExtension, AxTableExtension, etc.). This distinguishes it from sibling tools like find_event_handlers or find_references by precisely defining the resource and 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 guidance is provided: 'ALWAYS call before creating a new extension — avoid parallel customizations.' This tells the agent exactly when to use the tool and why, making the usage context unambiguous.

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

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

Annotations already declare readOnlyHint and idempotentHint, providing safety context. The description adds valuable behavioral context beyond annotations: the expensive O(1M+ chunks) warning, automatic handling of both label ID forms, and the exclusion for extensions-only searches. No contradiction with annotations.

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

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

The description is compact yet dense: every sentence adds essential information (purpose, usage context, cost warning, label handling, exclusion), with no filler. It is front-loaded with the most important info and structured logically.

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

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

For a read-only search tool with no output schema, the description covers the core purpose, when to use, cost, label special cases, and alternative tools. It is complete enough for an agent to select and invoke correctly, especially given rich sibling context and annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description slightly expands the meaning of 'name' to include fields and label IDs, but does not add significant detail for maxResults or locationsPerObject, which the schema already documents adequately.

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

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

The description clearly states the tool performs a full index scan for usages of object, method, field, or label ID, and it explicitly differentiates from siblings like find_callers and find_extensions. The verb 'find' and scope are specific and unambiguous.

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

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

Explicitly advises using it for impact analysis before changing/deleting an object, and gives concrete alternatives: 'Prefer find_callers when XRef index is loaded' and 'use find_extensions for CoC/event handlers.' This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: it returns both outgoing and incoming relations, delegates to get_relation_graph (O(1)) when the index is loaded, and advises against redundant calls. No contradiction.

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

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

The description is three sentences, front-loaded with the core purpose, then usage guidance and a performance/delegation note. Every sentence adds value with no redundancy.

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

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

For a single-parameter tool with no output schema and read-only/idempotent annotations, the description covers purpose, when to use, internal behavior, and alternative tools. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add parameter details beyond what the schema provides, but does not need to since objectName is self-explanatory and well-described in the schema.

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

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

The description clearly states the tool returns all FK/DeleteAction/DataSource relations (outgoing) and back-references (incoming). This specific verb+resource+scope distinguishes it from siblings like find_references and get_relation_graph.

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

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

Explicitly instructs to call BEFORE generating multi-object code, and warns not to call both this tool and get_relation_graph for the same object. This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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

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

Annotations declare readOnlyHint and idempotentHint, and the description supplements this with concrete behavioral details: traverses FK, DeleteAction, DataSource, Extension, Security edges in both directions; returns only names and relation kinds; O(1)-per-node BFS with no vector scan. This goes beyond what annotations express and sets expectations for output size and performance.

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 but well-structured, front-loading the WHEN and trigger phrases before the mechanism. Each sentence adds value: the graph edges detail, the token-light promise, and the comparison to the sibling tool. No tautology or filler.

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

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

Given there is no output schema, the description explains the return shape (chain of object names + edge kinds) and covers performance, scope, and alternatives. The tool is read-only and idempotent per annotations, and the description adds the specifics of graph traversal and limitations, making it sufficiently complete for an agent to select and invoke correctly.

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

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

Input schema covers all 4 parameters with full descriptions (100% coverage), so baseline is 3. The description adds context that source and target are object names, and explains the graph traversal includes both directions and the performance implication of maxDepth, which enriches understanding beyond the schema.

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

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

The description clearly states the tool's function: finding the shortest navigation path(s) between two AOT objects via the relation graph, returning a chain of object names and edge kinds. It distinguishes itself from sibling get_relation_graph by specifying this is for multi-hop traversal between two known objects.

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

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

Explicitly provides WHEN/trigger phrases (e.g., 'how is X related to Y') and directly contrasts with get_relation_graph: 'Use get_relation_graph for the full neighbourhood of a single object; use this to traverse multiple hops between two known objects.' This gives clear selection guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context by defining what 'similar' means (same kind, method set, field set), which helps the agent understand the matching logic. No contradictions with annotations.

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

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

The description is concise and front-loaded. The first sentence states the core purpose, and the second sentence adds a practical use case. Every word earns its place with no redundancy.

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

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

For a straightforward search tool, the description adequately explains purpose and use case. However, since there is no output schema, the description does not mention the return format or ordering, which is a minor gap. Overall, it is complete enough for an agent to select and invoke correctly.

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

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

The input schema fully describes all three parameters, including defaults and examples. The description adds no additional parameter semantics beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Find') and resource ('D365 objects') and clearly states the similarity criteria ('same kind, similar method set, similar field set'). This distinguishes it from sibling tools like find_references or find_related_objects, which serve different purposes.

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

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

The description provides clear context on when to use this tool: 'when you need a working reference implementation to copy from.' However, it does not explicitly exclude alternatives or name sibling tools for different scenarios, so it misses the top score.

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

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

The annotations already declare readOnlyHint and idempotentHint, and the description adds context about the optional Ollama dependency, the fallback to built-in suggestions, and the requirement for OLLAMA_HOST. This gives the agent a clear picture of potential side effects and dependencies beyond the basic read-only nature.

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

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

The description is structured with a 'WHEN' prefix and includes triggers and dependencies. It's a moderate length that covers necessary details without excessive verbosity. It could be slightly tighter but is well organized.

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

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

The tool has a moderately complex behavior with optional AI patches, but the description covers the core behavior, return value, fallback, and external dependency. Without an output schema, it explains what the agent can expect. It's complete enough for this complexity.

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

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

The input schema already provides descriptions for all three parameters (100% coverage). The description does not add significant new meaning beyond what the schema offers; it mentions generatePatches triggers Ollama, but that's already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns fix suggestions for BP violations and is meant to be used after validate_best_practices. It distinguishes itself from sibling validation tools by focusing on concrete X++ fix suggestions. The 'WHEN' opener makes the purpose explicit.

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

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

The description explicitly specifies when to use: after validate_best_practices returned violations. It also lists trigger phrases. However, it doesn't mention alternatives or exclusions like when not to use it, so it's clear context but no explicit exclusions.

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

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

Annotations include readOnlyHint=true, and the description adds that it produces complete XML with data sources, field mappings, entity key, IsPublic/PublicEntityName, and staging table template. This goes beyond the annotation but doesn't disclose return format or error behavior, so it's not a perfect 5.

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

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

The description is well-structured with 'WHEN', 'Triggers', 'Produces', 'Uses', and 'ALWAYS' sections. Every sentence carries value, including the trigger list which aids intent matching. No redundancy.

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

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

The description covers the tool's purpose, prerequisites, inputs, and produced artifact. Without an output schema, it lacks explicit output format details, but the main use case and trigger context are fully described. Could mention error scenarios, but overall it's quite complete.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The description enriches this by noting that it uses real field names/relations from the local model and that publicEntityName auto-generates if absent, adding meaning beyond the schema.

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

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

The description clearly states the tool creates an AxDataEntityView AOT XML from a table for OData/DMF/data migration. The verb 'CREATE' and specific resource 'data entity (AxDataEntityView) AOT XML' make it distinct from siblings like create_aot_object or generate_xpp_form.

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

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

The description explicitly states when to use it ('WHEN: developer needs to CREATE a data entity...') and lists trigger phrases for intent matching. It also mandates calling find_entity_for_table first to verify no standard entity exists, providing clear exclusion guidance.

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

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

With annotations already declaring readOnlyHint and idempotentHint, the description adds useful behavioral context: outputs are Mermaid diagrams that render in specific viewers, and the 'flow' type is disabled because static call trees are misleading due to CoC and event handlers. This goes beyond the annotations and explains a design decision.

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 somewhat long but well-structured, with sections for WHEN, triggers, types, and a note. There is no redundancy; each sentence contributes useful information. It could be slightly more concise, but the organization earns its length.

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

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

Given the tool's complexity (two active types, one disabled), a complete description is needed. It covers all diagram types, mentions rendering, and explains the disabled flow. It does not explicitly state the return format (Mermaid code), but that is reasonably inferred from 'Diagrams render directly in Copilot Chat...' so the description is sufficient.

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

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

The schema provides 100% coverage with descriptions, so the baseline is 3. The description adds meaning by elaborating on diagramType values ('er' for entity-relationship, 'security' for Role->Duty->Privilege->EntryPoints) and clarifying that methodName is unused because flow is disabled. This adds value beyond the schema.

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

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

The description clearly states the tool's function: 'Generate visual Mermaid diagrams from D365 F&O knowledge base data.' It specifies the two supported diagram types ('er' and 'security') and explicitly distinguishes from sibling tools like trace_security_chain, making its purpose unambiguous and well-scoped.

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

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

The description opens with 'WHEN: generating a visual diagram...' and provides triggers. It explicitly advises using trace_security_chain for structured text chains instead of the visual security diagram, and notes that 'flow' is disabled, offering clear when-to-use and when-not-to-use guidance with an alternative.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict this. The description adds useful behavioral context beyond annotations by listing the sections generated (Purpose, Business Context, etc.) and implying the output is a structured document ready for review, which is helpful for setting expectations.

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

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

The description is well-structured with WHEN, a summary sentence, output sections, and triggers. It is a bit lengthy due to the enumerations, but each part serves a purpose. It is front-loaded with the most critical usage guidance, making it efficient despite its length.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description covers usage triggers, exclusions, output structure, and purpose. It does not explain error handling or what happens if the objectName is invalid, but it is sufficiently complete for a document generator.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. The description mentions 'resolved labels' and sections but does not add extra meaning to the parameters themselves. It meets the baseline for schema-covered parameters but does not further elaborate.

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: 'Produces a structured FDD ready for review and sign-off.' It specifies the resource (Functional Design Document) and distinguishes it from sibling tools by explicitly excluding developer technical docs and pointing to get_object_details.

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

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

The description provides explicit when-to-use guidance: 'WHEN: user asks to write or generate a Functional Design Document...' and what not to use it for ('NOT for developer technical docs -- use get_object_details'). It also lists trigger phrases, making the decision easy.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, indicating safe read-only behavior. The description goes beyond this by detailing the tool's outputs (side-by-side X++ and SQL with explanations), its reliance on real field names/relations/indexes, auto-detection of joins, and the warning that output is a template. No contradictions with annotations.

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

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

The description is structured with clear sections (WHEN, supports, pre-requisites, caveat) and front-loaded with purpose. It is longer than ideal due to the extensive trigger list, but every sentence conveys useful information about usage, constraints, or output. The length is justified by the tool's complexity.

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

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

For a tool with 8 parameters, no output schema, and no nested objects, the description is exceptionally complete. It explains the return format (side-by-side X++ and SQL with explanations), pre-requisites for joins, supported query features (field selection, filters, order by, top, cross-company), and natural language input. It leaves little ambiguity about what the tool produces and how to use 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?

The input schema already covers all parameters with descriptions (100% coverage), providing a strong baseline. The description adds value by explaining the 'description' parameter (natural language auto-detection) and contextualizing parameters like top (firstonly) and crossCompany within the overall query-building workflow, though it does not detail each parameter.

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

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

The description clearly states the tool's function: generating X++ select statements and equivalent T-SQL queries for D365 F&O tables. It distinguishes itself from sibling tools by focusing on query generation and even instructs users to call find_related_objects first for joins, showcasing a specific resource and verb.

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

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

The description includes an explicit 'WHEN' section with trigger phrases and specifies the context for use. It also provides critical usage guidance: for multi-table joins call find_related_objects first, and notes that generated X++ is a template requiring adaptation. This clearly tells when and how to use the tool.

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

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

The description adds key behavioral context beyond the single readOnlyHint annotation: it produces two file types (Word and PowerPoint), returns download URLs, and explicitly states it does not invoke an LLM. This is important for setting agent expectations. It could mention potential side effects like file storage or permissions, but the disclosed behavior is already quite transparent.

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

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

The description is three sentences: the first gives a clear 'WHEN' condition, the second states the core action and output, and the third reinforces the no-LLM behavior. It is front-loaded, every sentence adds distinct value, and there is no wasted wording.

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 (8 parameters, no output schema) and the rich input schema, the description provides sufficient context: the prerequisite workflow, output formats, and the explicit no-LLM behavior. It does not describe error conditions or the exact structure of the returned URLs, but with 100% schema coverage, the missing pieces are minor for an agent to proceed correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some context by referencing the 'instructions' field from prepare_release_note_context and the 'objects' array, which helps relate findingsJson to the prior tool's output. However, this information largely overlaps with the schema descriptions, so it doesn't significantly elevate beyond the baseline.

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

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

The description clearly states the tool's function: it renders a findings array into downloadable Word and PowerPoint release notes and returns download URLs. The verb 'renders' is specific, and it explicitly differentiates from sibling prepare_release_note_context by requiring that the context has already been analyzed and a findings JSON produced.

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

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

The description opens with 'WHEN:' and provides an explicit prerequisite: the agent must have called prepare_release_note_context and analyzed the 'objects' array. It also gives a when-not by stating 'Does NOT call any LLM itself,' implying it should only be used after the reasoning is already done. This clearly establishes usage context and differentiates from the analysis-heavy 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?

Annotations declare readOnlyHint=true, and the description adds that it 'indexes' and 'infers' license tiers, plus surfaces orphan duties/privileges. However it does not explain what 'inferred user-license tier' means (e.g., heuristics), nor whether this is computationally expensive or requires a pre-built index. Enough to know it's safe, but lacking depth.

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

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

Three sentences, front-loaded with the core purpose, then details on content and unique output. No wasted words; every sentence adds value.

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

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

The description covers what the report includes and its unique 'orphan duties' feature. Given readOnly annotation and rich schema, no output schema exists but return format not explained. For a report tool, the main missing piece is output structure, but description adequately orients the agent. Contextually complete enough.

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

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

Schema has 100% description coverage for both parameters (filterModel, maxRolesDetail), each with clear explanations and defaults. The description reaffirms filterModel semantics ('Empty = all indexed models') but adds no additional meaning beyond the schema.

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

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

Description states a specific verb (generate) and resource (security & licensing governance report for indexed models), with clear scope: per-role duties/privileges/entry points/license tier. It distinguishes itself from related security tools like trace_role_license_tree or trace_security_chain by focusing on report generation and orphan access.

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