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

Beyond the annotations, the description discloses that preview is default, that validation covers object/type, CSDL and membership/dependency baseline, that parent shells may still be added, and that execution requires an explicit unprotected Action. It adds substantial behavioral context, though it does not fully spell out permissions or irreversible 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 dense but front-loaded and appropriately sized for a complex, destructive 14-parameter tool. Every sentence carries relevant information, though the single-paragraph format and heavy jargon reduce readability 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?

For a complex mutation tool with no output schema, the description covers preview versus execute, validation scope, component types, conditional logical_name, fixed flags, implicit parent additions, and post-execution verification. It still leaves minor gaps around permissions, how planHash is obtained, and exact preview output.

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

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

The description adds meaningful parameter context beyond the schema, especially the component type code mapping (1, 2, 9, 10, 14, 26, 60, 61, 90–93) and the conditional requirement that Attribute/Key requires logical_name. Schema coverage is 57%, and the description compensates for the missing enum and conditional-requirement details.

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

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

The description states a specific verb and resource: adding one existing component to a visible ordinary unmanaged solution, with preview as the default mode. It is clear what the tool does, though it does not explicitly name sibling tools like list_solution_components as 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?

It gives a clear usage protocol: preview by default, then execute with planHash plus an explicit unprotected Action, followed by rereading membership and reporting deltas. It does not explicitly state when not to use the tool or name alternative siblings, so it falls short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description goes further by explaining the write mechanism per cardinality and why the collection path needs allow_unprotected_write (parent ETags don't guarantee membership concurrency). It omits that a single-valued association overwrites the prior lookup value, which is the main destructive consequence an agent should know.

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, zero filler, and the core action is front-loaded before the mechanism detail. Dense technical vocabulary is used only where it carries information.

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

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

For a destructive, non-idempotent mutation with 15 parameters and no output schema, the description covers the two execution paths, the required safety flag, and the concurrency rationale. Remaining gaps are return shape and overwrite semantics, which are moderate but not fatal given the 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 80%, so the schema already documents collection_name, navigation_property, if_match, dry_run, and allow_unprotected_write, making 3 the baseline. The description adds real value by tying navigation_property cardinality to which write path and which flag are required, but adds nothing about the undocumented related_collection_name or the alias-conflict 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?

States a specific verb and resource ('Associate records') plus a constraint that scopes it to 'a validated native navigation property', which separates it from generic update tools like update_existing_record. It stops short of naming the obvious sibling disassociate_records or any alternative, so sibling differentiation is implied rather than 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?

Clearly routes between the tool's two modes: single-valued lookup goes through a conditional PATCH, collection membership goes through $ref and requires allow_unprotected_write. It does not say when to prefer this over update_existing_record or disassociate_records, so there is context but no 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 flag destructiveHint=true and idempotentHint=false; the description adds real context beyond them: immediate POST execution, dry_run doing metadata reads/validation only, expected_hash detecting changed metadata but not concurrent record changes, parameter values withheld unless explicitly opted in, and no Action replay. It does not cover permission requirements or failure behavior, keeping it below 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 purpose is front-loaded in the first sentence and no sentence is pure filler, but the prose is dense, jargon-heavy, and fragmented ('Preserves legacy defaults: Action POST and immediate execution, returning native data directly'), which slows comprehension for an agent scanning options.

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 16-parameter destructive tool with no output schema, the description covers execution model, preview/hash verification, return wrapping, binding modes, overload disambiguation, and alias safety. It is close to complete, lacking only error/failure semantics and permission prerequisites.

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 94%, so the schema already documents nearly every parameter including the alias pairs. The description adds marginal value, notably that dry_run withholds parameter values by default and that overload IDs disambiguate matching signatures. Baseline 3 is appropriate since the schema carries the load.

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

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

States a specific verb and resource: invokes a CSDL-defined Action/Function with typed validation. That is clearly distinct from data-CRUD siblings like create_new_record or execute_record_batch. It stops short of naming an alternative outright, relying on the schema's reference to get_api_operation for overload discovery.

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?

Implied usage is recoverable: use this for CSDL-declared Actions/Functions, and use dry_run to preview instead of executing. But the description never states when to prefer this over siblings such as get_api_operation, execute_record_batch, or update_existing_record, and 'Preserves legacy defaults' is not actionable guidance.

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

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

The description adds substantial context beyond annotations: the default dry-run preview mode, the execution preconditions (current expected_hash and allow_unprotected_write=true), MergeLabels=true behavior for updates, and explicit non-capabilities including no delete, renumber, state/status mutation, or automatic publish. This covers the destructive/write profile in a way annotations alone do not.

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

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

Five compact sentences, front-loaded with what the tool does, followed by constraints and execution requirements. There is no filler; every clause carries operational 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?

For a complex mutation tool with no output schema, the description covers the critical safety story: preview by default, execution gating, unmanaged-only scope, global choice addressing, and explicit no-op exclusions. It could say more about how to obtain expected_hash and the full parameter combinatorics, but it is largely complete for correct invocation.

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

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

With only 22% schema description coverage across 18 parameters, the description partially compensates by clarifying operation modes, the role of expected_hash and allow_unprotected_write, and the need to use global_choice_name for shared choices. However, it does not explain the solution_unique_name requirement, the logical_name/attribute_name pairing for local choices, alias handling, or value bounds, leaving many parameters under-documented.

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

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

States a specific verb+resource: insert a numeric choice option or update option labels/description. It names the native operations (InsertOptionValue/UpdateOptionValue) and distinguishes scope via 'Unmanaged choices only', so an agent can tell it apart from create_model_choices or publish_model_choices.

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

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

Gives clear usage constraints: unmanaged choices only, explicitly address a global choice to change shared values, default preview, and execution requires expected_hash plus allow_unprotected_write=true. It also lists exclusions (no delete, renumber, state/status mutation, automatic publish). It stops short of naming sibling tools as explicit 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 burden and does disclose what is discarded and that CRM data is untouched. However, it omits the consequences of clearing authentication tokens (forced re-authentication, possible follow-on call failures), whether the operation is reversible, and whether it affects other sessions or users.

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 short sentences, zero filler, and the highest-value information (what is cleared) is front-loaded. The scope disclaimer follows immediately rather than being buried.

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, unannotated utility the description covers what it does and what it leaves alone, but leaves meaningful gaps: no guidance on when to call it, no warning about the downstream effect of losing auth tokens, and no note on whether the clear is global or scoped to the caller.

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 takes zero parameters, so per the baseline a 4 applies; there is nothing for the description to disambiguate. No parameter claims are made that could conflict with the empty 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?

Uses a specific verb (clear) with two named resources (local cached metadata, authentication tokens) plus the effect on query continuations. The added 'Does not change CRM data' line separates it cleanly from the surrounding sibling tools, which all mutate or read CRM metadata and records.

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 never says when to invoke this tool — no trigger conditions (e.g., after schema edits, stale metadata, auth failures) and no alternatives or exclusions. The only boundary offered is a negative statement about what it does not affect, which is scope, not 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?

Adds substantial behavior beyond the readOnlyHint annotation: local execution without CRM settings, no authentication or environment switching, hash/checking rules, ignored transport fields, and the rule that gaps or ambiguous scope produce an inconclusive result rather than a false pass. It also discloses what the profile does not cover.

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

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

The purpose is front-loaded in the first sentence, and each subsequent sentence adds distinct value: comparison rules, reported differences, failure semantics, exclusions, and read-only execution. Despite the density, there is no filler.

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

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

For a complex nested-object comparison tool with no output schema, the description supplies the essential comparison semantics, integrity and scope rules, inconclusive-result behavior, and exclusions. It also sketches the return content by stating that missing, extra, and changed component references and property paths are reported.

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

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

Schema description coverage is 100%, so the baseline is 3; the schema itself documents sourceSnapshot, targetSnapshot, and expectedManaged in detail. The description adds useful comparison semantics around portable names, ignored GUIDs, and root scope, but does not add per-parameter guidance beyond what the schema already provides.

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

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

States a specific verb and resource — comparing two versioned snapshot objects — and immediately scopes it as local, without CRM settings. The offline/no-auth/no-environment-switching framing distinguishes it from sibling tools such as get_solution_snapshot and deployment verification 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?

Gives clear usage context: local snapshot comparison, plus explicit exclusions for option display order, unselected settings, full payload, managed layers, publication, and runtime. It does not explicitly name an alternative tool or say when another sibling should be used instead, so it falls short of the top guideline 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?

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: writes default to a dry-run preview, the tool verifies persisted labels and allocated values after execution, and publication is a separate step. The dry-run default meaningfully tempers the destructive 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?

Four tight sentences, front-loaded with the core action and prerequisites, with constraints following. A few telegraphic fragments ('Default preview.') are efficient rather than wasteful, though slight expansion would aid readability.

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 mutation tool with no output schema, the description covers the preview/write split and post-write verification reasonably well. It does not clarify the alias parameter duplication (which makes 'required parameters: 0' confusing) or what the preview response contains, leaving gaps an agent must resolve by reading the schema.

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

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

Schema description coverage is only 40%, so the description has to compensate, and it partly does: it explains omitting 'value' to get native publisher-based allocation and that supplied values/labels must be unique. However it says nothing about the schema_name vs schemaName alias pairs, the label/description language-code structure, or the display_name shape, leaving the camel/snake duplication unexplained.

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

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

States a specific verb and resource ('Create a global Picklist choice') plus prerequisites (existing unmanaged solution, publisher prefix), which distinguishes it from siblings like create_model_column, change_model_choice_value and publish_model_choices. It does not name an alternative explicitly, but the 'global' scope and 'no automatic publication' clause implicitly separate it from publish/update 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?

Guidance is present but mostly parameter-level: default preview behavior, when to omit an option value, and the note that publication does not happen automatically (implying a separate publish call). There is no explicit statement of when to choose this over get_model_choices or create_model_column, so usage must be inferred.

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 flag destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds genuinely new context: creation is staged (preview by default, publication is a separate step) and it runs parent-managed-property, publisher-prefix, and duplicate-logical-name validation before acting. What's missing is any note on permissions or side effects of the validation failures.

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

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

Four dense sentences with the type list front-loaded and the workflow caveat at the end. The type enumeration partially duplicates the schema enum, but the sentence is tightly packed with no filler.

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

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

For a 33-parameter, no-output-schema mutation tool, the description covers the critical workflow semantics (dry-run default, separate publication, validation checks) but leaves most type-specific parameters undocumented, so an agent would have to reverse-engineer the schema to fill in a valid call.

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 33 parameters and only 12% schema description coverage, the schema documents almost nothing, and the description does not fill the gap. It mentions choice binding via local options or global_choice_name and type-specific validation, but max_length, precision, format, required_level, date_time_behavior, default_value, min/max values, and the label structures are left entirely unexplained.

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

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

States a specific verb (create) and resource (column) and enumerates the nine supported column types, which lets an agent distinguish it from create_model_table and create_model_choices without opening the schema. It stops short of naming a sibling explicitly, so it lands at 4 rather than 5.

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

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

The line 'Default preview; save and publication remain separate' implies the dry-run-first workflow, and the validation checks hint at preconditions, but there is no explicit statement of when to choose this over create_model_choices or create_model_table. Guidance is implied rather than stated.

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 flag destructiveHint=true and non-idempotency, but the description adds substantial context beyond them: a default preview/dry-run mode, asynchronous server-side validation of index size and existing uniqueness, and the state caveat that 'Pending/unknown is not Active'. It also draws explicit boundaries around side effects ('No record scan, index reactivation, save replay or implicit publication'), which is exactly what an agent needs before committing a destructive mutation.

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

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

Front-loaded with the core action and column limit, and the following sentences are dense with distinct facts rather than repetition. The telegraphic fragment 'Pending/unknown is not Active' and the clipped negation list at the end cost some readability but still carry information.

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

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

For a destructive, non-idempotent create tool with no output schema and only 33% schema coverage, the description does solid work on side-effect boundaries, async validation and preview semantics. The main gap is that it never clarifies the effectively-required parameter set (all five logical fields, in either casing) or what the preview payload actually contains.

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

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

Schema description coverage is only 33%, so the description must compensate and it only partly does: '1–16 columns' maps to key_attributes' maxItems, 'solution/publisher' maps to solution_unique_name, and 'type, field-security and duplicate checks' gesture at validation behavior. It says nothing about the five logical parameters (logical_name, schema_name, display_name, key_attributes, solution_unique_name), their dual snake_case/camelCase aliasing, or which are effectively required.

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

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

States a specific verb and resource: 'Create a native alternate-key definition on 1–16 columns', which clearly separates it from create_model_column, create_model_relationship and create_model_table. The clause 'No ... index reactivation' implicitly distinguishes it from reactivate_model_key, but no sibling is named explicitly, so it stops short of the top score.

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?

'Default preview' and 'No ... save replay or implicit publication' imply the intended workflow (dry-run first, publish separately), which is useful context. However, it never states when to prefer this tool over reactivate_model_key or get_model_key, nor does it spell out prerequisites such as an existing unmanaged solution, so usage is only 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?

Annotations already declare destructiveHint=true and non-idempotent, and the description adds real value by describing the dry-run default, the eligibility checks run (publisher, managed properties, duplicate names) and the absence of implicit publish. However it never surfaces the destructive consequence the annotations warn about, so the agent still learns nothing about what execution actually mutates.

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

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

Four short sentences with the primary action and the authoring/dry-run model front-loaded. Slightly dense with comma-separated check lists, but nothing is redundant.

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

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

For a 19-parameter, nested-object mutation with no output schema, the description covers the preview semantics and the eligibility checks but leaves the majority of parameters and the shape of returned preview data unexplained. Adequate orientation, insufficient detail.

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 19 parameters and only 21% schema description coverage, the description must carry the load, yet it only gestures at lookup creation and cascade rules. Key discriminators like entity_1/entity_2 versus referenced/referencing entities, intersect_entity_name, and how schema_name relates to solution_unique_name are left unexplained.

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

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

Opens with a specific verb and resource ('Create native 1:N ... or N:N relationship') and names the distinct shapes each type requires. It is clearly separable from the sibling get_model_relationship and update_model_relationship, though it never names them directly.

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

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

Explains that the default is a preview pass and that execution requires opting out, and the negative clause ('No ... update of existing relationships') routes the agent away from reusing this for edits. The exclusions are implied rather than tied to a named alternative 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?

Adds real context beyond the annotations: creation defaults to a preview/dry run and the tool deliberately stops short of form placement and publication, so the agent knows the operation is staged. With destructiveHint=true and readOnlyHint=false already declared, the preview default is the key mitigating detail and it is disclosed. What is not covered is reversibility of a created table or 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?

Three dense sentences with the creation intent first, prerequisites second, and side-effect exclusions last. No restatement of the name and no filler.

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

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

For a destructive, 15-parameter creation tool with no output schema, the description covers the decisions an agent must get right: dry-run default, solution/publisher prerequisite, and what the tool intentionally omits. It stops short of describing the execute-mode response or ownership-type implications, but nothing critical to correct invocation is missing.

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

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

At 27% schema description coverage across 15 parameters (many duplicated as snake/camel aliases), the description carries real weight but only explains a few: the primary text name column, the solution requirement, and publisher-prefix validation. Ownership type, description, display collection name, maxLength, and the language_code/text label structure are entirely left to the schema.

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

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

States a specific verb and resource ("Create an ordinary custom table with a primary text name column") and qualifies the table type ("ordinary"), which implicitly excludes other table kinds. It also names the underlying mechanism (native EntityDefinitions). It does not explicitly contrast itself with siblings such as create_model_column or create_model_relationship, leaving that to the resource noun.

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?

Prerequisites are spelled out: an existing unmanaged solution and matching publisher prefixes. It also delineates scope by stating it does not place fields on forms or request publication, which implicitly routes the agent to publish/field tools afterwards. No explicit named alternatives, but the when/when-not conditions are clear.

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

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

Annotations already declare destructive=true and idempotent=false, so the safety profile is covered. Beyond that, the description adds genuine context: accepts returned entity/ID headers or a supplied primary key, reports confirmed save separately from ID availability, and dry_run previews without writing — behavior an agent could not read from annotations alone.

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 short sentences, front-loaded with the create action, then the ID-handling nuance, then the dry_run preview. Slightly telegraphic phrasing ('Accepts returned entity/ID headers') borders on ambiguity but nothing is wasted.

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

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

For a write tool with no output schema, the description usefully pre-announces return behavior ('reports confirmed save separately from ID availability') and the dry_run escape hatch. It leaves required data/collection_name requirements to the schema, which is fair given 100% coverage, but a note on validation failure behavior would complete it.

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

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

Schema description coverage is 100%, so the schema itself documents data, dry_run, and the collection_name/collectionName alias pair thoroughly. The description only gestures at 'a supplied primary key' and dry_run and adds no syntax or constraint detail beyond what the schema already provides; baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Create a native record') and the schema clarifies the target as a native entity set such as 'accounts'. It distinguishes reasonably well from model-metadata siblings (create_model_table, create_model_key) by working on records rather than schema, though it never explicitly contrasts with the closely named sibling upsert_record_by_key.

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 what dry_run does, which implies when to preview, but it never states when to use this create vs. alternatives like upsert_record_by_key or execute_record_batch. The agent must infer create-vs-upsert semantics from the tool names alone.

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 a non-read-only, non-idempotent, destructive operation, while the description adds valuable behavior: no overwrite of an existing saved name, default publish after save, dry-run preview without writes, and preservation of saved=true and the created ID when publishing fails. It omits authorization requirements but adds substantial context beyond the structured 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?

Four tight sentences front-load the purpose, then cover defaults, preview behavior, and error recovery. Every sentence adds useful information without repetition.

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

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

For a 16-parameter create-and-publish tool with no output schema, the description covers critical state transitions and recovery behavior well. It does not describe the normal success response in detail, but that is a minor gap given the rich schema 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 high at 88%, so the schema already documents aliases, enums, file/content constraints, and type mappings. The description reinforces publish and dry_run behavior but does not add much parameter meaning beyond what the schema provides.

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

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

The description uses a specific verb and resource (create a Web Resource) and adds the key scope constraint that it will not overwrite an existing saved name. This clearly distinguishes it from sibling update and publish tools.

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

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

It explains the default publish behavior, how to save without publishing via publish=false, how to preview with dry_run=true, and how to recover from a publication error using publish_web_resource. It does not explicitly direct existing-resource updates to update_web_resource_and_publish, but the create-only scope is clear.

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

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

With readOnlyHint already declaring the safety profile, the description adds real value: it names what is deliberately excluded from results (content, credentials, configuration) and flags that completeness is bounded. That tells the agent results may be truncated, which annotations alone would not convey.

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

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

Three tight sentences with the core purpose front-loaded and no filler. The phrase 'bounded completeness is explicit' is slightly abstract/self-referential but still earns its place by flagging truncation.

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?

A read-only list tool with no output schema, so the description needn't explain return values. It covers exclusions and bounded results but leaves the pagination/limit parameter and the alias duplication unexplained, which matters for a 4-param tool with zero schema documentation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It conveys that ID/name filters are exact-match, which is useful, but says nothing about the `top` limit, its 500 maximum, or the assemblyId/assembly_id alias pair — half the parameters remain opaque.

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

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

States a specific verb and resource: 'List native plugin assembly metadata'. The clause 'Does not invoke the .NET reader' implicitly distinguishes it from the d365_plugin_assembly_inspect sibling, so an agent can tell which one to reach for, though the sibling is not named outright.

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 only implied. The exclusion of content/credentials/configuration and the note about the .NET reader hint that this is for lightweight metadata listing rather than full inspection, but there is no explicit 'use X instead when you need Y' routing to d365_plugin_assembly_inspect.

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

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

Beyond the readOnlyHint annotation, the description discloses that it uses a fixed .NET 10 metadata-reader process, does not require CRM settings, does not execute the inspected code, and does not verify signatures or resolve dependencies. This adds meaningful safety and limitation context.

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

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

The description is compact and front-loaded: it states the core capability first, then the operating context, then the explicit non-goals. Every sentence contributes useful information.

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

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

For a read-only local inspection tool without an output schema, the description covers what metadata is read and what is explicitly not done. It could be slightly more complete by routing users to the appropriate CRM/query sibling for registered assembly metadata.

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 filePath/file_path and contentBase64/content_base64. The description does not add parameter-specific meaning beyond noting local use and no CRM settings, 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 states a specific verb and resource: reading DLL identity, target framework, public plugin contract types, and reference metadata. It distinguishes itself from CRM-oriented siblings by saying it works locally and requires no CRM settings.

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 implies usage for local DLL inspection and gives exclusions such as no code execution, signature verification, or dependency resolution. However, it does not explicitly name when to use this over siblings like d365_plugin_assemblies_query or d365_plugin_registration_metadata.

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 destructive and non-idempotent annotations, the description discloses preview defaults, validation rules, blocked change categories, concurrency gating, post-save verification, and the .NET runtime requirement. This is unusually rich behavioral context for an update operation.

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

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

The description is dense but largely free of filler, and most sentences carry essential constraints or safeguards. It is somewhat run-on and leads with 'Default preview only' rather than an explicit purpose statement, which slightly hurts readability.

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, destructive update tool with no output schema, it covers the critical safety and validation model well, including preview, fingerprinting, concurrency, and verification. It still leaves gaps around permissions/auth expectations and the exact shape of the preview or save result.

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 71%, so the schema already documents many parameters. The description adds conceptual context around preview fingerprints and metadata-gated concurrency, but it does not meaningfully explain key parameters such as assembly_id or expectedFingerprint beyond what the schema and naming imply.

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 makes clear that this is a controlled update of an existing plugin assembly from a DLL, with preview-first behavior and preservation of plugin type IDs. It distinguishes itself from creation and step-retargeting, but it never explicitly names the sibling tools or states 'update plugin assembly' as a crisp purpose sentence.

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

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

It gives strong usage context: preview by default, execute only with the preview fingerprint, and do not use it to create assemblies or retarget steps. It also lists blocked scenarios, but it stops short of explicitly routing the agent to alternative tools such as inspection or query 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 already declare destructive=true and idempotent=false, and the description goes well beyond them: it explains the preview-then-write fingerprint requirement, metadata-gated concurrency, the unusual 404-based confirmation semantics, and that a failed write is not retried. That is exactly the extra context a destructive, non-idempotent tool needs.

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 dense sentences with zero filler: identity and scope first, prerequisites second, boundaries third. Nothing is repeated from the schema and no sentence could be removed without losing a call-relevant fact.

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

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

For a destructive 10-parameter tool with no output schema, the description covers the critical behavior (preview gating, fingerprint, confirmation, scope limits). It leaves implicit where the fingerprint comes from (a dry-run of this same tool) and says nothing about what the preview returns, which is the one remaining 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 80% and the individual parameters (dry_run, if_match, expected_fingerprint, allow_unprotected_update) already carry their own descriptions, so the baseline is 3. The description reinforces the fingerprint and exact-ID constraints but adds no new detail about the concurrency opt-in or alias pairs.

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

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

States a specific verb (delete) and resource (an unmanaged customizable plugin image) qualified by 'by exact ID', which is precise enough to separate it from the sibling d365_plugin_image_register, d365_plugin_image_update and d365_plugin_images_query tools. The 'Preview/delete' framing also flags the dual dry-run/live mode up front.

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

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

Gives clear operational conditions: preview first, supply the fingerprint from that preview, and confirm deletion via a subsequent 404. It also draws an explicit boundary ('Does not delete its parent step or retry a write'), though it never names which sibling to use for parent-step removal or for a plain image lookup.

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 destructiveHint=true and readOnlyHint=false; the description adds meaningful context beyond them: the mandatory preview-fingerprint gate before a destructive write, validation of stage/message and overlapping aliases, and the dry-run-first intent. It stops short of describing irreversibility or result shape, but the safety path is clearly disclosed and consistent with the destructive 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?

Five short sentences, each carrying distinct information (capability, supported steps, validation, write gate, exclusions), with the core purpose front-loaded. A few phrases such as 'explicit readable fields' are slightly opaque but not wasteful.

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

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

For a destructive mutation tool with no output schema, the description covers the write gate, validation behavior, and scope exclusions adequately. It could say more about what a preview returns (the fingerprint object) and the meaning of the 13 parameters, but the operational essentials 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 description coverage is low (31%) across 13 params, so the description must compensate. It does add conceptual meaning for image_type (Pre/Post/Both), attributes (explicit readable fields), entity_alias (entity-specific), and expected_fingerprint (required to write), but leaves name, description, step_id, and the alias duality unexplained.

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

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

States a specific verb pair (Preview/register) and resource (native Pre/Post/Both image) plus the scope of supported steps (Create, Update, Delete, Assign, SetState). It is readily distinguishable from siblings like d365_plugin_image_update and d365_plugin_image_delete.

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 two-phase workflow is explicit: preview first, then write requires a preview fingerprint. It also scopes out what it does NOT do (no assembly upload, no automatic publication). It does not explicitly say when to use this versus d365_plugin_image_update, leaving that to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description contributes genuine beyond-schema behavior: results are bounded and self-report completeness, and continuation links are deliberately not followed. This tells the agent to check completeness rather than assume an exhaustive list — a meaningful operational caveat.

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

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

Two tightly packed sentences with the scope stated first and the behavioral caveats second. No filler, though the phrase "bounded results report completeness" is somewhat compressed and takes a second read.

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

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

For a read-only single-purpose query with no output schema, the description covers what it returns and how truncation behaves, which is the critical piece. It stops short of describing what a native image record contains or how the step identifier is obtained, leaving gaps an agent must fill from trial or siblings.

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

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

Schema description coverage is 0% across three parameters, so the description must carry the load and largely does not. It only hints that the step identifier is matched exactly; `top`, the stepId/step_id aliasing, the UUID format constraint, and the anyOf-one-of requirement are left entirely to the caller to infer from the schema.

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

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

States a specific verb and resource: "List native images for an exact step." The qualifier "without reading plugin configuration" distinguishes it from heavier inspection siblings like d365_plugin_assembly_inspect, though it never names an explicit alternative.

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

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

Usage is implied rather than stated: you already know the step and want only its images, avoiding the cost of reading plugin configuration. There is no explicit when-not condition or named sibling to use instead (e.g. when the step id is unknown, use d365_plugin_steps_query).

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 destructive=true and non-idempotent, and the description adds meaningful confirmation-side detail beyond them: omitted patch values are preserved (partial-semantics), validation runs against fields, parent step and duplicate aliases, and saved fields are read back. It doesn't spell out consequences of a bad update or permission requirements, but the added disclosure is well past the annotation baseline.

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 verb and resource, with no redundant restatement of the title. The second sentence compresses four distinct behaviors into one clause chain, which is dense but still parseable.

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

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

For an 11-parameter, nested-object mutation with no output schema, the description covers the preview-to-write flow, partial-patch semantics, the validation gates, the fingerprint requirement and the read-back return. Missing only sibling routing and explicit failure/concurrency edge 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?

Coverage is 73% and the schema already documents dryRun, ifMatch, expectedFingerprint and allowUnprotectedUpdate. The description still adds real semantics the schema lacks: patch is a partial patch whose omitted values are preserved, and a preview fingerprint is mandatory for the write path. It leaves the ifMatch/allowUnprotectedUpdate interplay to the schema, so not a 5.

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

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

States a specific verb+resource ("Preview/update an unmanaged customizable image") and the tool name plus sibling naming convention (image_register, image_delete, image_update) makes the target obvious. It doesn't explicitly contrast itself with those siblings in the text, so it stops short of a 5, but the operation is unambiguous.

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

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

The description implies the workflow (preview first, then a fingerprint-gated real write) and names prerequisites for the write path. It never states when to choose this over d365_plugin_image_register or d365_plugin_image_delete, nor any exclusions, so usage is only implied rather than prescribed.

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

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

readOnlyHint=true already covers the safety profile, yet the description still adds real value: it warns that listings are bounded and report limits (i.e. results may be truncated) and that metadata presence does not prove write permission. It also clarifies the tool never uploads assemblies, ruling out a mutation an agent might assume from a 'plugin registration' 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?

Three short sentences, front-loaded with the discovery scope, followed by the two key caveats. No filler and nothing buried.

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 discovery tool with full schema coverage and no output schema, the description covers scope, truncation behavior and the write-permission caveat. What it omits is any sense of the shape of results (e.g. whether listings are grouped per message or assembly), which an agent would benefit from when interpreting output.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, including the alias semantics and the 'omit for global registration' note on primary_entity. The description's mention of SDK messages, assemblies and plugin types loosely maps to message/assembly_name/plugin_type_name but adds no syntax or constraint details beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb ('Discover') and enumerates the concrete resources: plugin types, assemblies, SDK messages and message filters. It is clearly a read-only metadata listing tool, but it doesn't explicitly name the sibling it differs from (e.g. d365_plugin_assemblies_query or d365_plugin_assembly_inspect), so sibling differentiation is only implied by the 'does not upload' clause.

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?

'Bounded read-only listings report limits' and 'Does not upload assemblies' hint at when this tool is appropriate and when it isn't. However, no alternative tool is named and there is no explicit statement of when to prefer d365_plugin_assemblies_query or d365_plugin_steps_query over this one, leaving selection to inference.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so the description's job is limited to adding context, and it does: no automatic replay of the write, secure configuration is allocated as a separate row and bound during create, and all phases report IDs on failure. That partial-failure/ID-reporting detail is genuinely useful and not derivable from the schema or 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?

Five tight sentences, front-loaded with the core action before the validation, configuration, and preview details. No filler, though the secure-configuration sentence is dense enough that a shorter phrasing would read faster.

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 26-parameter mutation tool with no output schema, the description covers the important unknowns: dry_run as a non-writing preview, partial-failure ID reporting, and secure configuration handling. It does not say what a successful call returns (e.g. step ID/shape), which is the main remaining gap given the absence of an output schema.

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

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

Schema description coverage is 85% across 26 parameters, so the schema already carries the burden, including enums, aliases, and dry_run semantics. The description adds only the aggregate notion that message/entity filters are resolved and filtering fields validated, which explains behavior rather than individual parameters; specific parameter meaning is left to 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 first sentence gives a specific verb and resource ("Register a step for an existing native plugin type"), which separates it from the query/update siblings by implication. It never names d365_plugin_steps_query or d365_plugin_step_update explicitly, so the differentiation relies on the reader inferring register-vs-read-vs-modify.

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

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

Usage is implied by "Register a step for an existing native plugin type" plus the note that dry_run previews without writing, which tells an agent how to do a safe rehearsal. There is no explicit when-not guidance, no mention of the update/query siblings, and no statement of prerequisites such as needing the plugin type to already exist in the target environment.

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

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

With readOnlyHint already declaring the safety profile, the description adds genuinely non-obvious behavior: Secure Configuration is suppressed by default and requires explicit opt-in plaintext read, all filters combine conjunctively, and output volume is capped by top. It does not cover permission requirements or what happens when no filters are supplied.

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 short sentences, each carrying distinct information: purpose first, then the security-relevant default, then filter/output semantics. No repetition of schema content and no filler.

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

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

For a 17-parameter read tool with no output schema, the description covers the highest-risk behaviors (secure configuration exposure, conjunctive filtering, result bounding). It leaves the caller to infer the no-filter case and whether a zero-match or error is returned, which matters given only top bounds the result set.

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 88%, so the schema already documents nearly every parameter including the alias mappings and enum values; the baseline is 3. The description contributes additional meaning about step_id combining with other filters and the secure-configuration default, but adds nothing about alias conflict handling, defaults, or the relationship between top and the absent filter set.

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

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

States a specific verb and resource ("Query native plugin steps") plus the filtering model ("exact filters"), which is enough to separate it from mutation siblings like d365_plugin_step_register/update. It stops short of naming the nearest read alternatives (d365_plugin_assemblies_query, d365_plugin_registration_metadata), so the agent must infer which query tool to pick.

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

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

The description explains the semantics of using the tool (filters are ANDed, secure config is opt-in, results capped) but never says when to choose it over the sibling query tools for assemblies, images, or registration metadata. Usage is implied by the noun "plugin steps" rather than explicitly routed.

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 destructiveHint=true but say nothing about concurrency or configuration handling; the description fills that gap with concrete behavior: table concurrency metadata plus a specific ETag by default, secure set creating a replacement row bound in the same PATCH, clear unbinding, and existing rows never blindly deleted. It stops short of stating required permissions or what a write/readback failure response looks like beyond "preserve phase evidence".

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

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

Six short sentences, front-loaded with the one-line purpose, then progressively narrower behavioral facts (patch semantics, concurrency, secure configuration, failure evidence). No sentence restates the name or title and none is padding.

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

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

For a destructive, 13-parameter mutation with nested configuration objects and no output schema, the description covers the risky parts an agent must know: omit-keeps, ETag concurrency, replacement-row semantics, and failure evidence. It leaves auth/permission requirements and error signaling implicit, which is the main remaining gap.

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

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

Schema coverage is 69%, so the schema already documents most parameters (if_match, dry_run, configuration actions). The description adds the non-obvious defaults — that omitting if_match uses the current step ETag and that table concurrency metadata drives the decision — plus the keep/set/clear model, but does not explain allow_unprotected_update or the alias pairs. Mid-coverage baseline of 3 fits.

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

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

Opens with a specific verb+resource ("Update one plugin step"), which an agent can distinguish from d365_plugin_step_register, d365_plugin_steps_query, and d365_plugin_image_update in the sibling list. It never names an alternative explicitly, but the operation is unambiguous from the first four words.

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 never states when to choose this tool over d365_plugin_step_register or the image-update sibling, nor does it mention prerequisites such as needing an existing step or how it relates to querying first. Patch semantics ("omitted fields are kept") describe how the call behaves, not when to make 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?

The annotations already declare destructiveHint=true and readOnlyHint=false. The description adds useful context about validated GUIDs, concurrency conditions, dry-run preview behavior, and ETag handling, though it does not mention required permissions or whether deletion is irreversible.

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 compact sentences, front-loads the core delete action, and wastes no words while including key safety-relevant details.

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

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

Given the destructive annotations and rich schema, the description provides enough context to invoke the tool correctly, including dry-run and concurrency behavior. It could be slightly more complete by mentioning permission requirements or dependency/cascade effects, but those are not strictly required here.

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

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

Schema description coverage is 89%, so the schema already carries most parameter meaning. The description references GUID validation, dry_run, and ETag semantics, but it does not add much beyond the detailed schema descriptions for if_match, allow_unprotected_write, and alias 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 a specific verb and resource: it deletes a native record, with validated GUID and concurrency conditions. This distinguishes it from sibling update/upsert/get record tools without requiring schema inspection.

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 explains that dry_run identifies the target without deleting, which implies preview usage, but it does not explicitly state when to choose this tool over alternatives such as update_existing_record, upsert_record_by_key, or get_record_by_id.

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

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

Annotations only declare readOnly/non-destructive; the description adds substantial behavioral context beyond them: that missing, forbidden, and limited sources are reported, that root cause is deliberately left undetermined, that current step state is not historical config, that include_text opts into business data with secure columns never selected, and that bounded reads report incompleteness.

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

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

Two dense sentences, front-loaded with the core action and source list, with caveats packed at the end. Efficient for a 17-parameter tool, though the warnings are terse to the point of being easy to skim past.

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

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

For a complex, no-output-schema tool the description covers the sources, anchoring, safety, and limits well. It does not describe the resulting report's sections or how the sources are correlated, which would help an agent interpret results, but the essentials 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 82%, so most parameters are documented in the schema itself. The description adds the semantic of the anchoring keys (correlation, step, plugin type) but says nothing about top, max_pages, from_time/to_time defaults beyond what the schema already states; baseline 3 is appropriate.

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

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

States a specific verb and deliverable ('build a read-only evidence report') and names the three data sources (exception-filtered traces, failed jobs, current plugin steps) plus the anchoring keys. It implicitly distinguishes itself from single-source siblings like query_plugin_trace_logs and query_failed_system_jobs by being a composite, though it never names them.

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

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

The context ('anchored by correlation, step or plugin type') and the caveat 'Current step state is not historical configuration' imply a diagnostic/forensic use case, but there is no explicit when-to-use or when-to-prefer-sibling guidance despite many adjacent query tools. Usage must be inferred.

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 destructiveHint=true already declared, the description adds meaningful context: it is a conditional removal (matching target only), collection membership follows a different code path, and related records are not deleted. It does not disclose the dry_run/if_match workflow or what a partial/no-op result looks like, but the scope of destruction is well clarified.

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 short sentences, front-loaded with the core action, then the two semantic modes, then the safety caveat. Nothing is padded, though it could be slightly tighter.

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 15 parameters, no output schema, and concurrency controls (dry_run, if_match, allow_unprotected_write), the description covers the association semantics well but omits the operational workflow (preview first, ETag handling) and idempotency behavior. Adequate, not complete.

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

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

Schema coverage is 80% with detailed per-property descriptions (including alias handling, dry_run, if_match, allow_unprotected_write), so the schema carries the parameter burden. The description mentions no parameter names or formats, leaving the baseline of 3 appropriate.

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

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

States a specific verb and resource ('Remove a native association'), which plainly contrasts with the sibling associate_records. It does not name the sibling explicitly, but the operation is unambiguous.

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

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

The description implies usage conditions — a lookup is cleared only when it points at the supplied target, and collection membership goes through a $ref DELETE — but it never states when to prefer this tool versus associate_records or update_existing_record, nor any 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?

Goes well beyond the annotations (destructiveHint=true, non-idempotent, non-readonly) by disclosing the preview-by-default safety model, the optimistic concurrency gate via expected_hash, the ETag check with allow_unprotected_write fallback, and that publication is not automatic. It also states what is intentionally not supported, which prevents misuse.

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?

Dense but front-loaded: purpose, allowed operations, exclusions, then safety/execution notes. Every sentence carries information, though a couple of clauses (ETag/allow_unprotected_write) are packed tightly and could be slightly clearer.

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

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

For a 14-parameter destructive mutation with no output schema, the description covers the critical decision points (preview vs execute, concurrency protection, no auto-publish) and the operation family. It stops short of describing per-operation payload requirements, but the schema's structure plus these safety notes are largely sufficient to call it correctly.

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

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

Schema description coverage is only 29%, so the description must compensate. It does explain the key gating parameters (expected_hash, allow_unprotected_write, dryRun) and hints at template_control_id via 'compatible existing control template', but leaves many operation fields (section_id, attribute_name, control_id, label, pass_execution_context) undocumented. Partial compensation only.

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

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

States a specific verb and resource ('Structurally edit a Main form') and then enumerates exactly the three operations supported: add_field, add_library, bind_event-style bindings. An agent can distinguish this from sibling tools like edit_model_view or edit_ribbon_solution without opening the schema.

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

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

Gives clear usage context: default is preview, execute requires expected_hash (or allow_unprotected_write), and lists exclusions (no arbitrary XML, no PCF/Lookup template copying, no code execution). It does not explicitly name alternative sibling tools for other form/editing needs, but the when-to-use conditions are clear.

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

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

Annotations only say it is a destructive, non-idempotent write; the description adds substantial context beyond that: destructive-but-structural scope (filters/joins preserved), explicit rejection of aggregate/distinct rewrites, dry-run default preview, fingerprint plus metadata-gated ETag/fallback safety checks, saved readback verification, and that publishing is not automatic.

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

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

Front-loaded with the core purpose in the first clause, and every subsequent sentence adds a distinct constraint. The final sentence is a dense comma-spliced fragment ('Default preview, fingerprint and metadata-gated ETag/fallback checks, saved readback, no automatic publish') that is efficient but slightly telegraphic.

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

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

For a destructive, non-idempotent mutation with no output schema and 14 loosely documented parameters, the description covers safety gating, preview default, readback verification and the no-auto-publish consequence. It omits required permission/solution-prerequisite context and rollback behavior, leaving a modest 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?

With only 29% schema description coverage, the description compensates well by explaining the dryRun preview default, the fingerprint (expectedHash) and ETag (ifMatch) gating, and the four operation shapes in the operations array. It leaves allow_unprotected_write and the identifier/aliasing parameters unexplained, which holds it below a 5.

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

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

States a specific verb and resource ('Structurally edit a public system view') and then enumerates the exact edit categories: add/remove root display columns, set widths, replace root-field ordering. This is clearly distinguishable from siblings like edit_model_form or update_model_column_settings.

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

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

Gives clear scope boundaries — it preserves filters/joins/FetchXML attributes and rejects aggregate/distinct query rewrites, which tells the agent when this tool is inappropriate. It stops short of naming a specific alternative for those rejected rewrites, so it is clear context rather than full when/when-not/alternative 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?

Adds substantial context beyond the annotations: dry-run defaults to preview with no file written, execution writes an exclusive NEW ZIP and never overwrites the input, and preservation guarantees for other languages/rules/handlers and other archive payloads are spelled out. Consistent with destructiveHint=false and readOnlyHint=false since the input archive is never mutated.

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

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

Front-loading is good ('Preview by default') and every clause carries real content, but the body is three very long run-on sentences packed with comma-chained constraints. It is dense to the point that an agent must parse carefully to extract the operational rules.

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 13 parameters, 62% schema coverage, no output schema and a mutation workflow, the description covers safety, idempotency/hash flow, preservation semantics and out-of-scope work well. It leaves a gap on what the preview/execute returns (presumably a planHash plus summary) and how the agent obtains that hash for the execute call.

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?

Description explains the changes model at a semantic level (publisher-scoped IDs, explicit current-table insertion location, ordered parameters, multilingual labels, packaged JS/raster icons) that the schema's structural constraints do not convey, and it flags the planHash requirement. However it says 'planHash' while the schema field is expected_hash, a naming mismatch that could cause confusion, and dry_run/output path handling is only partially reinforced.

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

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

States a precise verb+resource: editing classic RibbonDiffXml in an ordinary unmanaged local ZIP, including the specific sub-operations (add custom JS button, update labels/sequence, set visibility). It also explicitly distinguishes itself from siblings by naming what remains separate (built-in replacements, arbitrary rules, handler updates, modern commands, deployment), which separates it from inspect_ribbon_solution, import_ribbon_solution and publish_ribbon_solution.

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

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

Gives clear scope boundaries: 'Preview by default', 'never overwrite input, import, publish or run code', and lists workflows that remain separate. It stops short of telling the agent to call inspect_ribbon_solution first or to run preview then execute with the returned hash, so the sequencing is implied rather than prescribed.

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

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

Goes well beyond the annotations (readOnly=false, destructive=true) by disclosing the non-atomic change-set model, preflight validation before dispatch, per-item outcome reporting, the stop-on-unknown-results safety rule, and cancellation handling. These are exactly the behavioral traits an agent needs before committing destructive 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?

Two tight sentences, front-loaded with the verb, scope, and batching model; each subsequent clause carries a distinct behavioral fact with no filler.

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

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

For a destructive, multi-operation tool with no output schema, the description adequately covers execution model, failure semantics, and outcome reporting. The main gap is the absence of routing guidance versus execute_record_transaction, which an agent would still need to infer.

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

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

Schema description coverage is 86%, so aliases, dry_run, chunk_size, if_match, and operation variants are already documented in the schema. The description only reinforces the 100-item cap and chunking model, adding little syntax or format detail beyond structured fields.

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

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

States a specific verb and resource ('Execute up to 100 validated record mutations in native $batch chunks') with a clear scope. The non-atomic, per-change-set semantics implicitly distinguish it from the transactional sibling, but no sibling is named explicitly, so it falls short of a 5.

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

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

The behavior described (no rollback across operations, preflight, per-item outcomes) implies this is for multi-mutation batches where partial success is acceptable, but the description never states when to choose this over execute_record_transaction or when to avoid it. Usage is left to inference.

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

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

The annotations already declare a destructive, non-idempotent mutation, and the description adds important behavior: committed=false for confirmed rejection and unknown for transport/server ambiguity, plus preflight scope and rejection of unsupported dependency patterns. It still does not fully explain atomicity/rollback semantics or authentication requirements.

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

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

Three sentences, front-loaded with the core action and constraints. Each sentence adds a distinct behavioral or scope constraint, with no filler or repetition.

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

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

For a complex destructive batch tool with no output schema, the description covers transactional scope, capacity, failure ambiguity, and unsupported patterns. Some details remain implicit, especially full result structure and whether all operations are atomic, but the schema carries most operation-level detail.

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 moderate at 67%, with detailed field descriptions for dry_run, operation shapes, and aliases. The description adds the 100-operation cap and dependency rejection, but it does not explain dry_run or the specific operation types beyond what the schema already provides.

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

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

The description states a specific verb, resource, and scope: executing up to 100 validated mutations in one native $batch change set. It distinguishes itself from chunking and individual writes, though it does not explicitly name the sibling tool execute_record_batch. The core purpose is clear and actionable.

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

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

It gives clear constraints: up to 100 operations, one native batch, no chunking or fallback to individual writes, preflight reads outside the transaction, and no arbitrary HTTP or Content-ID dependencies. It does not explicitly name sibling alternatives such as execute_record_batch, so selection guidance is strong but not complete.

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 only declaring it is not read-only and not idempotent, the description carries the real behavioral load: writes an exclusive new local .zip, never returns base64, never overwrites files, does not publish, and on failure the reserved path may be empty or partial with no automatic replay. That is exactly the failure-mode and side-effect detail an agent needs before invoking a write.

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

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

The default and safety constraints are front-loaded ('Preview by default') and every clause carries information, with no filler. It is telegraphic to the point that some sentences ('Native ExportSolution from a visible ordinary unmanaged source') require domain knowledge 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 no-output-schema, multi-mode write tool the description covers workflow, file-writing guarantees, publish behavior, and failure recovery, which is substantial. The unexplained planHash reference and the undocumented expectedHash parameter are the remaining holes.

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 44% and the description adds meaning for two of the nine parameters: managed output must be chosen explicitly and execution requires a current preview planHash. However, planHash is referenced but does not exist in the schema (additionalProperties: false), and expectedHash — a 64-hex verification parameter — is never explained, leaving a real gap.

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

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

The description states a specific verb and resource — exporting a solution via Native ExportSolution into a local .zip — and distinguishes the preview vs. managed output modes. It does not name the closest siblings (inspect_solution_package, import_solution_async) so the boundary is inferred rather than stated, and the phrasing is compressed to the point of being cryptic in places.

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?

'Preview by default' plus 'Execute with planHash' communicates the two-phase preview-then-execute workflow, and 'choose managed output explicitly' tells the agent unmanaged is the default. No exclusion against alternative inspection/export siblings is given, so it falls short of a full when/when-not statement.

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

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

Consistent with readOnlyHint=true. Beyond the annotation, the description discloses return-shape limitations an agent would otherwise discover the hard way: only direct input type definitions are returned and nested types are not expanded, and the metadata does not guarantee permissions or runtime support. That is real behavioral context, not restated 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?

Four short sentences, front-loaded with the pull operation and its scope, then limits, then the caveat — no filler. Slightly reduced by heavy jargon packing ('CSDL', 'facets') with no expansion, which costs an unfamiliar agent a re-read.

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

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

There is no output schema, and the description does shoulder that burden by describing what is returned (direct input type definitions) and what is truncated (nested types). With 7 parameters including alias pairs and a nested binding object, the description covers the main semantics; only overload-disambiguation guidance and how to act on the results are left implicit.

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

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

Schema coverage is 86%, so the baseline is 3, but the description adds genuine meaning beyond the schema: it explains what the nested 'binding' object accomplishes (narrowing signatures by entity set) and frames is_function as the Action/Function selection. Only signature_id disambiguation is left to the schema text, which already covers it well.

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

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

The description states a specific verb and resource: read the service CSDL to inspect Action/Function overloads, parameter types/facets, binding and import names. That scope is clearly narrower than the entity-metadata siblings (get_entity_metadata_summary, list_all_entity_definitions), but it never names the invocation counterpart call_d365_api_action, so the discovery-vs-invocation split has to be inferred.

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?

'Optional entity-set binding narrows signatures' hints at how to disambiguate, and the closing caveat ('read-only metadata does not prove permissions/runtime support') hints that verification requires an actual call. However, it never says explicitly when to use this instead of call_d365_api_action or the other metadata inspectors, so routing remains 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?

Annotations already establish read-only/non-destructive, and the description adds real behavioral context on top: old/new values are withheld by default and only projected on explicit opt-in, projection is bounded and heuristically masked, and detail vs. summary permissions are reported separately. That is genuine disclosure beyond the structured fields, though the truncation/masking mechanics stay at a high level.

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

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

Three sentences with no filler, but the opening clause 'Read native bound RetrieveAuditDetails' is low-information jargon that pushes the actually useful content (opt-in bounded values, separate permission reporting) behind it. Front-loading is weak for an agent skimming definitions.

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 should convey something about the return shape, yet 'other detail types are named without fabricating unsupported fields' and 'summary metadata' remain undefined. It covers the value-withholding behavior adequately but leaves an agent guessing what a response actually contains.

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 83%, so the schema already explains include_values, max_text_chars, and the aliases; the description mostly restates the opt-in/bounded semantics in prose. It adds the useful note that unsupported fields are named rather than fabricated, but no parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

The verb 'Read' and the resource ('audit details' plus 'audit summary metadata') are present, but the phrasing 'native bound RetrieveAuditDetails' is opaque API jargon rather than an agent-readable statement of what comes back. It never distinguishes itself from the sibling get_record_audit_history, so an agent must infer that this is per-audit-entry detail while the sibling is per-record history.

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?

There is no explicit when-to-use or when-not guidance, and no mention of get_record_audit_history as the alternative for listing a record's audit trail. The only implicit usage signal is 'opt-in' on attribute values, which tells the agent a flag exists but not when this tool is the right choice.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. 'Get' implies a read-only operation, but the description does not state permissions, side effects, response shape, or any other operational detail beyond the broad subject of retrieval.

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

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

The description is a single front-loaded sentence with no wasted words. However, its extreme brevity contributes to gaps in behavioral and contextual detail, so it is not a perfect 5.

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

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

For a zero-parameter read tool, the description is minimally adequate: it says the tool returns information about the current user and organization context. But with no output schema and no annotations, it should say more about what information is returned or any relevant constraints.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description does not introduce confusion about 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 uses a clear verb ('Get') and specific resource scope ('information about the currently connected user and organization context'). It is understandable without opening the schema, but it does not explicitly distinguish itself from nearby context/security tools such as get_principal_security_context.

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

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

The description states what the tool retrieves but gives no explicit guidance on when to use it versus alternatives or when not to use it. Usage is only weakly implied by the phrase 'currently connected user and organization 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?

No annotations are provided, so the description carries the full burden, yet it discloses almost nothing behavioral: it doesn't say whether the call is read-only (only implied by "Get"), what volume or shape of metadata comes back, or whether the attribute must exist. "Full metadata details" is the only behavioral signal, and it is undefined.

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

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

A single front-loaded sentence with the resource stated immediately; no repetition or padding. The trailing "for deep analysis" is the only soft phrase, but it does hint at the depth of the response.

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?

This is a simple two-parameter read tool, but with no output schema and no annotations the description should say at least roughly what "full metadata" includes (types, constraints, picklist data?) so the agent can decide between this and sibling metadata tools. As written it is adequate but leaves the return contents and the summary/detail trade-off unexplained.

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

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

Schema description coverage is 100%, with both required parameters (entity_logical_name, attribute_logical_name) documented in the schema itself, so baseline 3 applies. The description adds no extra semantics such as where logical names come from or case-sensitivity — it merely echoes "attribute (field)".

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 pairs a specific verb ("Get") with a specific resource ("full metadata details for a specific attribute/field"), and the word "full" implicitly contrasts with summary-level siblings. It never names those siblings (get_entity_metadata_summary, get_field_picklist_options) outright, so the differentiation is left implicit rather than 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?

"For deep analysis" is the only usage cue and it is vague — it doesn't tell the agent when to prefer this over get_entity_metadata_summary or get_field_picklist_options, nor what prerequisites (e.g. logical names must already be known) apply. There is no explicit when-to-use or when-not-to-use guidance.