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

Beyond the annotations, it discloses the exact field mutated (acknowledged=true), the idempotent behavior on repeat calls, and that a work note is optional. It does not cover permissions or the response payload, keeping it short of a 5.

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

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

Three compact sentences with the effect stated first, then the parity comparison, then the idempotency caveat. The trailing '**[Write]**' tag is mildly redundant given readOnlyHint=false, but nothing is padded.

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

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

For a two-parameter write tool with no output schema, the description covers the mutation, idempotency, and the optional note. The only gap is that it hints at but doesn't state what the response contains for already-acknowledged alerts.

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

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

Schema description coverage is 100% for both parameters, so the schema already carries their meaning. The description only reinforces that work_notes is optional and attached to the acknowledgement, which is marginal added value.

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 ('Acknowledge an alert') and pins down the exact effect ('sets acknowledged=true, exactly like the "Acknowledge" list action'). It does not explicitly contrast with siblings like update_alert or close_alert, 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 note that already-acknowledged alerts are 'reported, not re-written' implicitly says when this call is a no-op, which helps selection. However, there is no explicit guidance on choosing this over update_alert or close_alert, 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?

Goes well beyond the annotations by disclosing downstream effects: advancing the attached workflow and transitioning the underlying VR record, plus the rejection-requires-comment rule and the WRITE_ENABLED=true gate. It does not state whether a completed approval is reversible or what happens if the workflow is already advanced, which is notable given idempotentHint=false.

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

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

Two sentences plus a bracketed prerequisite note; the action, the object, the side effect, and the rejection constraint are all front-loaded 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 3-parameter mutation with full schema coverage and no output schema, this covers the essentials: valid target record, observable side effects, and the write-enable prerequisite. Missing only failure-mode behavior (invalid/already-resolved sys_id, workflow state conflicts).

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

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

Schema coverage is 100%, so the schema already explains sys_id, the action enum, and that comments are required on reject. The description restates the rejection/comment rule without adding format, length, or example guidance, 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?

States a specific verb pair (approve/reject) and a precisely scoped resource (Vulnerability Response approval, sysapproval_approver) keyed by sys_id. This clearly separates it from the generic approve_request/reject_request and the read-only list_vr_approvals sibling.

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

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

Scope is implied by naming the VR approver table, so an agent can infer this is the VR-specific alternative to generic approval tools, but no sibling is named and there is no explicit when-not guidance. The WRITE_ENABLED prerequisite is a useful gate but is framed as a caveat, not a usage condition.

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

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

Annotations already convey the write nature (readOnlyHint=false) and non-idempotency. The description adds valuable context: the comment is customer-visible and requires WRITE_ENABLED=true. This goes beyond the annotations and gives the agent important operational knowledge.

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

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

A single sentence that conveys the core action, scope, and a critical requirement. No fluff, front-loaded with the verb, and all words earn their place.

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

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

For a simple 3-parameter tool with fully described schema and annotations, the description is complete enough for invocation. It does not discuss return values, but since there is no output schema and the operation is straightforward, this is acceptable.

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

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

Schema coverage is 100% and the schema already describes each parameter, including 'Comment text (visible to end user/caller)'. The description adds little beyond the schema, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Add'), identifies the resource ('customer-visible comment'), and scopes it to 'any ITSM record'. It clearly distinguishes from the sibling 'add_work_note' by specifying the comment is customer-visible, making the tool's purpose unambiguous.

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

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

The description provides clear context ('customer-visible', 'any ITSM record') and a prerequisite ('requires WRITE_ENABLED=true'). It implies when to use this tool vs. internal work notes, but it does not explicitly name an alternative or state when not to use it.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses the WRITE_ENABLED=true requirement. This adds operational context not present in the annotations, though it does not cover idempotency or duplicate membership behavior.

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

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

Single concise sentence that front-loads the purpose and includes a key requirement. No wasted words.

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

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

For a simple mutation tool, the description plus schema and annotations provide sufficient context. It names the operation and a key prerequisite, though it could mention what happens if the user is already in the group, but this is not critical given the sibling tool context.

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

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

Schema coverage is 100% and both parameters have clear descriptions ('System ID of the user' and 'System ID of the group'). The description adds no additional information beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Add a user to a group' with a specific verb and resource, distinguishing it from sibling tools like 'remove_user_from_group' and 'update_group'.

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

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

Provides a necessary prerequisite (WRITE_ENABLED=true) but no explicit guidance on when to use this tool versus alternatives like remove_user_from_group. Usage context is implied by the name and description.

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=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, and the description adds a genuinely useful operational constraint: the call requires WRITE_ENABLED=true. It also discloses the underlying m2m table, which explains that this writes a link record rather than modifying either entity. It does not warn about duplicate associations despite idempotentHint=false.

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

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

Two tight sentences: the action and mechanism come first, the entity semantics second, and the bolded write/environment requirement last where it is easy to scan. The m2m table name is implementation-level but still earns its place by clarifying the write target.

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

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

For a two-parameter write tool with full annotation coverage and no output schema, the description supplies what matters: what relationship is created, which record type the group must be, and the environment flag needed to succeed. The main gap is behavior on an already-existing association, which matters given idempotentHint=false.

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

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

Schema coverage is 100% and both parameters already document themselves as sys_ids, so the baseline of 3 applies. The description largely restates the schema's explanation of the remediation_group ('backs the remediation task'), adding a little entity context but no new naming, format, or lookup guidance.

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

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

The description names a specific verb (associate) and the exact relationship being created (Vulnerable Item ↔ remediation group via sn_vul_m2m_vul_group_item), so an agent can distinguish it from create_remediation_task or list_remediation_task_findings. It stops short of explicitly naming those siblings as alternatives, which keeps it from 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?

Usage is implied rather than stated: 'the group is an sn_vul_vulnerability record that backs the remediation task' tells the agent what the remediation_group parameter must point to, which implies this tool is for linking, not creating tasks. There is no explicit when-to-use vs. create/update_remediation_task guidance or prerequisite ordering.

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

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

Annotations already indicate a non-read-only operation (readOnlyHint=false). The description adds the 'internal' nature (not visible to end user) and the WRITE_ENABLED requirement. These provide some context beyond annotations, but the description does not explain what happens on failure or whether the note is appended or overwrites existing content.

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 that states the action and a key prerequisite. No redundant filler or restatement of the tool name. It earns its place.

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

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

For a simple mutation with a fully described schema, the description is adequate but minimal. It omits what happens on success (e.g., return value) or failure, and whether the note is added to the activity log. Since no output schema exists, a bit more detail about effects would improve completeness.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no extra meaning beyond the schema, such as format of sys_id or examples for table. It only restates that it works on 'any ITSM record', which aligns with the table parameter's description.

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

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

The description clearly states the action ('Add'), the specific resource ('internal work note'), and the scope ('any ITSM record'). The word 'internal' distinguishes it from sibling tool 'add_comment', which presumably adds a visible comment, so the purpose 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 does not provide guidance on when to use this tool versus alternatives like 'add_comment' or 'update_record'. It mentions a prerequisite ('requires WRITE_ENABLED=true'), but this is a constraint rather than usage direction. No exclusions or alternative tool references are given.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints, so the bar is lower. The description adds context about the semantic AI-powered nature, which is a behavioral trait beyond 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?

Single sentence of 12 words, front-loaded with key info, no wasted words. Every part contributes to understanding the tool's core function.

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 annotations and schema, the description sufficiently covers what the tool does. It lacks mention of return format or pagination but is complete enough for an AI to select this tool over siblings. No output schema exists, so some inference is needed.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema listings for query, sources, and limit. It matches but does not enrich the parameter understanding.

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

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

The description clearly states the tool performs semantic AI-powered search across specific resources (KB, catalog, incidents), using a specific verb. It distinguishes from siblings like search_knowledge or search_catalog by indicating it covers multiple sources.

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

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

The description implies usage for cross-source search but does not explicitly state when to use this tool versus alternatives like natural_language_search or individual source searches. No exclusions or when-not-to-use guidance provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds context on what aspects are checked but doesn't detail how (e.g., whether it samples or scans all records). No contradiction with annotations.

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

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

Extremely concise, one sentence that front-loads the purpose. No unnecessary words.

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

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

Does not explain the output format or return value. An agent needs to know whether results are returned as scores, lists, or something else to interpret them correctly.

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

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

Schema coverage is 100% with descriptive parameter descriptions. The tool description hints at how parameters relate to quality checks but adds minimal additional meaning beyond the schema.

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

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

The description clearly states it analyzes data quality for a table, listing specific aspects (completeness, duplicates, stale records). This differentiates it from siblings like check_table_completeness which likely focuses only on completeness.

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?

No explicit guidance on when to use this tool versus alternatives like check_table_completeness or compare_record_counts. Usage is implied but not clarified.

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

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

Annotations already indicate write operation (readOnlyHint=false) and idempotency (idempotentHint=true). Description adds the WRITE_ENABLED prerequisite, which is useful. However, it does not disclose side effects (e.g., workflow triggers, notifications) or post-approval behavior, leaving room for improvement.

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

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

Single sentence with critical prerequisite in parentheses. No superfluous words. Front-loaded with verb and resource. Excellent conciseness.

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 explain what the tool returns (e.g., success status, updated record) and any side effects (e.g., workflow triggers). It does not. For an approval tool with moderate complexity, this is a significant 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 covers 100% of parameters with descriptions. The description does not add additional semantic information about the parameters beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

Description specifies the verb 'Approve' and the resource 'pending approval request', clearly distinguishing from sibling tools like reject_request and list_approvals. It includes a prerequisite, making the purpose immediately understandable.

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

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

The description explicitly states a required condition (WRITE_ENABLED=true). While it does not provide explicit when-to-use vs when-not-to-use, the verb and sibling context implicitly guide usage: this tool is for approving, not canceling or rejecting. Missing explicit exclusions, but clear overall.

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

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

Annotation contradiction: annotations declare readOnlyHint=false and idempotentHint=false, while the description states 'Retrieve' which implies a read-only, idempotent operation. The description does not disclose any additional behavioral traits such as limits, authentication, or error semantics, and contradicts the provided 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?

One sentence, zero wasted words. The description is front-loaded with the action and object, making it immediately understandable.

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

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

The tool lacks an output schema and the description does not mention return format, constraints, or error behavior. More importantly, the annotation contradiction undermines trust and the description is not sufficient to resolve it. For a simple tool, this is incomplete.

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

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

The input schema fully describes the single parameter 'names' as an array of property names with 100% coverage. The description adds no extra parameter context beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('retrieve') and resource ('system property values'), and explicitly scopes to 'multiple' and 'single call', distinguishing it from single-property getters like get_system_property and listing tools.

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

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

The description implies usage for fetching multiple property values at once but does not explicitly contrast it with alternatives or state when not to use it. It lacks explicit when/when-not guidance, though the intent is reasonably clear from the wording.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds transparency about the upsert behavior (create or update) and the batch nature, which are not fully captured by annotations. However, it omits details on error handling or limits.

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

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

The description is extremely concise with a single sentence and a brief tag, containing zero wasted words. It front-loads the essential information.

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

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

Given the tool's complexity (batch upsert, no output schema), the description is adequate but misses important context such as maximum batch size, error reporting, and return value format. It covers the core functionality but leaves gaps.

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

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

The input schema provides high coverage (100%) with a clear structure for the 'properties' array. The description adds minimal extra semantics beyond restating that it operates on multiple system properties. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Create or update multiple system properties in a single operation,' specifying the action (create/update), resource (system properties), and batch scope. It distinguishes from the sibling tool 'set_system_property' which operates on a single property.

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

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

The description implies usage for batching but does not explicitly state when to use this tool over alternatives like 'set_system_property' or 'import_properties'. No when-not or alternative guidance is provided.

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

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

Annotations already indicate destructiveHint=true. The description adds the requirement for WRITE_ENABLED and specifies that the request must be 'open', providing useful behavioral context beyond 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?

Single sentence with no unnecessary words. Straightforward and efficient.

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

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

Given no output schema, the description provides essential context: it cancels an open request and requires a specific configuration. It is sufficient for the agent to understand the tool's function.

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 descriptions already cover both parameters with adequate detail. The description does not add significant extra meaning beyond the schema context of 'open service catalog request'.

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

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

The description clearly states the verb 'Cancel' and the resource 'open service catalog request'. The prerequisite 'requires WRITE_ENABLED=true' adds specificity. This distinguishes it from siblings like 'approve_request' and 'reject_request'.

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

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

The description provides a clear prerequisite (WRITE_ENABLED=true) and implies usage for open requests. However, it does not explicitly state when not to use it (e.g., if the request is already closed) or mention alternative tools.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. Description adds algorithm version but no additional behavioral traits like error handling or output format.

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

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

Single sentence, front-loaded with purpose, no redundant text.

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

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

No output schema, and description does not describe the prediction result format. For a tool that returns predictions, the output structure is crucial context.

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

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

Schema provides full descriptions for both parameters. Description adds 'for better accuracy' but no new semantic detail beyond schema.

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

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

The description clearly states it predicts category, assignment group, and priority using Predictive Intelligence with LightGBM. It distinguishes from sibling tools like ml_train_incident_classifier and get_incident.

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?

Implies use for prediction on incident data, but does not explicitly state when to use vs alternative prediction tools or exclude scenarios. No when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and external-network behavior are covered structurally. The description adds the data-flow detail (installed version sourced from sys_scope, compared against public Store history) and that release notes are returned, but says nothing about failure modes when an app is not found in the Store or how the catalog search resolves ambiguity.

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 then the use case, with no filler. The second sentence is a sentence fragment ('For upgrade planning of...'), which reads slightly awkwardly, but the content earns its place.

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

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

No output schema exists, so the description carries the burden of describing results, and it does state that the release notes of every newer version are returned. Remaining gaps (ordering limits, behavior when no newer version exists) are minor for a read-only diagnostic tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine routing semantics beyond the schema: the listing_id vs store_query vs default-app-name fallback chain. That mutual-exclusivity/fallback logic is not obvious from the schema alone.

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

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

States a specific verb+resource: compares the installed version (from sys_scope on the instance) against the public Store version history and returns release notes for newer versions. The comparison framing implicitly separates it from get_store_app_versions/search_store_apps, but it never names those siblings, so an agent must infer the distinction.

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 concrete usage context – 'For upgrade planning of Store apps (VR, ACC Framework, ...), whose lifecycle is independent of platform upgrades' – which tells the agent when this applies versus platform-upgrade tooling. It also routes between parameter modes ('Provide either listing_id, or store_query / nothing'), but offers no explicit 'do not use when' exclusion.

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

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

With readOnlyHint=true already declared, the description goes further by explaining exactly how access is probed (sysparm_limit=1 GET for reads; empty PATCH to a reserved all-zero sys_id for writes, with 404=writable/403=denied) and explicitly guarantees 'no record is ever created or modified'. This resolves the apparent tension between a PATCH and a readOnly annotation rather than contradicting it.

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

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

The critical guidance ('BEFORE attempting operations', the status vocabulary, the non-destructive guarantee) is front-loaded. It runs a bit long with the parenthetical status enumeration, but every clause carries actionable information rather than 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?

There is no output schema, and the description compensates fully by enumerating the return fields (per-table readable/writable flags, status values with their meanings, current user and roles). For a two-parameter diagnostic tool with annotations, nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining the mechanism behind check_write (non-destructive empty PATCH) and what its outcome signifies. The 'tables' parameter's max-20 cap is left to the schema, which documents it adequately.

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

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

States a specific verb and resource ('Diagnose the connected service account's effective access to one or more tables') and immediately contrasts with operational siblings by saying it runs BEFORE attempting operations. An agent can distinguish this from describe_table, query_records, or get_record without inspecting any 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?

Explicitly frames the when: 'BEFORE attempting operations' and names two concrete use cases (verifying a plugin is installed, avoiding 'User Not Authorized' retries). It stops short of naming the alternative tools to call after a successful check, so it is strong context rather than a full routing rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and openWorldHint=true, indicating a safe, idempotent, and open-world operation. The description adds the output detail (percentage returns) but does not elaborate on other behavioral aspects like sampling behavior or error handling. It does not contradict annotations.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose. However, it could be improved by front-loading the most critical information, such as the resource and verb, which it does, but it lacks structure for 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?

The description provides a high-level overview but does not explain the return format (e.g., dictionary of field names to percentages), pagination, or potential limitations (e.g., sampling behavior). Given no output schema, this omission is a gap. The description is adequate but not comprehensive.

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

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

Schema description coverage is 100%—all four parameters have descriptions in the schema. The tool description does not add any additional meaning beyond the schema. Baseline score of 3 applies since the schema already documents parameters adequately.

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

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

The description clearly states the verb 'Analyze', the resource 'data quality and field completeness for a ServiceNow table', and the output 'returns percentage of non-empty values per field'. It is specific and distinguishes from sibling tools like 'analyze_data_quality' by focusing on field-level completeness.

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?

No guidance is provided on when to use this tool versus alternatives such as 'analyze_data_quality', 'get_table_record_count', or 'query_records'. The sibling list includes many related tools, but the description does not help the agent decide when to select this one.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds a minimal verb but no extra behavioral context such as whether the original is preserved, what fields are copied, or if scope is required. It does not contradict annotations, but also does not enrich them beyond the basic clone semantics.

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

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

The description is a single, front-loaded sentence that directly states the tool's purpose. The [Scripting] tag adds minimal but potentially useful context. Every word earns its place with no waste.

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

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

The tool is a straightforward clone operation with all parameters documented in the schema. There is no output schema, and the description does not explain return behavior or side effects. Given its simplicity and full schema coverage, the minimal description is acceptable but does not go beyond the bare essentials.

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

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

Schema description coverage is 100%, with clear descriptions for each parameter (table, sys_id, new_name, target_scope). The description's 'new name/scope' phrasing maps to the new_name and target_scope parameters, but adds no extra 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 uses a specific verb ('Clone') and resource ('platform artifact') with explicit outcome ('to a new name/scope'). It clearly distinguishes itself from sibling artifact tools like push_artifact, pull_artifact, and sync_status by focusing on duplication rather than transfer or synchronization.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or comparisons to similar artifact operations. The context is implicit from the verb 'clone,' but no explicit when-to-use or when-not-to-use guidance is given.

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 this as destructive, non-idempotent, and open-world, so the description's job is to add context — and it does: the resulting state, the conditional acknowledgment side effect when evt_mgmt.alert_ack_on_close is true, and a documented failure mode for already-Closed alerts. It does not describe permissions required or the response payload, keeping it below a 5.

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

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

A single front-loaded sentence states the action, the resulting state, the conditional side effect, and the refusal precondition with zero filler. The [Write] marker is a compact safety signal.

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

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

For a two-parameter mutation with rich annotations and no output schema, this covers the state transition, the side effect, the precondition, and optionality of the note. Only the error/return behavior and any permission requirements remain unstated.

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

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

Schema coverage is 100% and both parameters are documented there, so the schema carries the semantics. The description only adds that the work note is optional at close time, which is a marginal addition beyond what the schema already states.

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 (close an alert) plus the resulting state (state=Closed), which is more than a restatement of the name. It also hints at the acknowledge side effect, which separates it from acknowledge_alert, but it never names that sibling explicitly, so differentiation is implicit rather than spelled out.

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

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

The description gives one useful precondition (refuses alerts already Closed) and implies the tool is for final resolution, but it never says when to prefer acknowledge_alert or update_alert instead. An agent must infer the routing from sibling names.

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

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

Annotations already indicate destructive behavior, so the description does not need to restate that. It adds the operational requirement 'requires WRITE_ENABLED=true', which is useful context beyond annotations. However, it does not disclose other behavioral details such as state transitions or irreversibility.

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

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

A single sentence that is front-loaded with the action and resource, includes the key requirement, and has no wasted words. It communicates the essential information efficiently.

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

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

For a simple mutation tool with full annotations and complete parameter schema, the description covers the core action and a prerequisite. It lacks output schema or error handling details, but for a straightforward close operation, this is reasonably complete.

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

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

Schema description coverage is 100%, with all three parameters (sys_id, close_code, close_notes) already described. The description merely mentions close code and notes without adding new detail, so it does not add significant value beyond the schema.

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

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

The description uses the specific verb 'Close' targeting the 'change request' resource, with close code and notes as key parameters. This clearly distinguishes it from sibling tools like close_incident, close_hr_case, and update_change_request.

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

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

The description implies usage for closing change requests and mentions a prerequisite (WRITE_ENABLED=true), but does not explicitly contrast with alternatives like update_change_request or state when closing is appropriate. The guidance is present but not explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the mutation risk is known. The description adds the WRITE_ENABLED prerequisite, which is useful, but it does not disclose consequences such as the case being irreversibly moved to a closed state or any side effects. Given the annotation coverage, the description adds minimal context beyond the requirement.

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

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

The description is a single, front-loaded sentence that immediately states the action and object, followed by the key permission requirement. There is no wasted wording, making it highly concise.

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

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

For a simple three-parameter tool, the description is adequate but missing context about the closing workflow—it doesn't explain that closing is typically a terminal action or what response the agent should expect. The lack of an output schema means the return value is unspecified, and the description does not clarify whether the tool returns the closed case or a simple success indicator. Still, the essential purpose and required permission are covered, earning a moderate score.

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

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

Schema description coverage is 100%, with each parameter already documented with a concise description. The description's phrase 'with resolution details' only reinforces the importance of resolution_notes but adds no new syntax, format, or value constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states a specific verb ('Close') and resource ('CSM case') with the qualifier 'with resolution details', distinguishing it from sibling tools like create_csm_case, get_csm_case, and update_csm_case. It also names the permission prerequisite, although that's not purpose.

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

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

The description provides no guidance on when to use this tool versus update_csm_case or close_incident. It does not state that closing is a final action or that it should be used after resolution is complete. There are no explicit exclusions or alternative tool mentions.

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

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

Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false). The description adds the WRITE_ENABLED=true prerequisite, which is useful operational context, but doesn't elaborate on irreversibility, side effects (despite openWorldHint=true), or return behavior. No contradiction with annotations, but limited additional behavioral disclosure.

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: 'Close an HR case with resolution notes (requires WRITE_ENABLED=true).' It conveys the verb, resource, input, and a critical prerequisite with no filler or redundancy.

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

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

For a 3-parameter tool with rich annotations (destructiveHint, readOnlyHint, idempotency, openWorld) and full schema coverage, the description and annotations together provide a solid operational picture. The WRITE_ENABLED prerequisite is a valuable addition. The only omission is return value/confirmation behavior, which is minor given the simple close action and lack 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 100%, with all three parameters (sys_id, close_code, close_notes) already documented. The description's 'with resolution notes' merely reiterates the close_notes parameter without adding format, examples, or constraints. 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 the specific verb 'Close' with the explicit resource 'HR case', clearly distinguishing it from sibling tools like close_incident, close_change_request, and update_hr_case. The 'with resolution notes' phrase adds meaningful specificity about the tool's primary function, making it 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 tool is for closing HR cases with resolution notes, but provides no explicit guidance on when not to use it or which alternatives apply (e.g., update_hr_case for non-closing modifications, close_csm_case for CSM cases). An agent relies primarily on the tool name and sibling context rather than explicit direction.

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

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

Annotations already indicate a destructive, non-read-only operation, so the description adds extra context by specifying the WRITE_ENABLED=true requirement and the precondition that the incident must be resolved. This goes beyond what annotations provide, though it omits details about side effects or reversibility.

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 that immediately states the verb and object, with a useful parenthetical for the permission requirement. No wasted words; every part contributes to understanding the tool's purpose and precondition.

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 simplicity of the tool (one parameter, no output schema), the description covers essential aspects: what it does, when it can be used (resolved incident), and a system-level requirement. It does not explain return values, but since annotations and schema are already rich, this is sufficient. Minor gap is lack of detail on what 'closing' implies beyond 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?

The schema has 100% coverage on the single parameter sys_id, so the description need not elaborate. The description does not add any additional meaning about parameters, which is acceptable given the schema's clarity. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Close') and a specific resource ('incident'), and further qualifies it as 'resolved incident', which clearly distinguishes this tool from siblings like resolve_incident or update_incident. The parenthetical about WRITE_ENABLED adds a clear precondition, making the purpose unambiguous.

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

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

The description clearly implies when to use this tool: only for incidents that have been resolved. It also identifies a prerequisite (WRITE_ENABLED=true). However, it does not explicitly name alternatives or state when not to use it, so it falls short of a perfect score.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that it returns metrics on completeness but does not disclose output structure, caching, or rate limits. With annotations present, the description provides minimal additional behavioral context.

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

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

Single sentence that is front-loaded and contains no extraneous information. Every word serves a purpose.

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

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

Despite no output schema, the description only vaguely mentions 'metrics (completeness of server and network CI data)', leaving the return format and structure unclear. With openWorldHint, the agent may expect a collection but lacks detail on field names or types.

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?

No parameters exist, and schema coverage is 100% (vacuous). The description correctly implies no input is needed, so it fully compensates for parameter understanding.

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

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

The description uses specific verb 'Get' and resource 'CMDB data quality metrics' with explicit scope 'completeness of server and network CI data', clearly distinguishing it from sibling tools like 'analyze_data_quality' or 'check_table_completeness'.

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?

No explicit guidance on when to use this tool versus alternatives like 'analyze_data_quality' or 'cmdb_impact_analysis'. The description implies a specific dashboard context but lacks comparative or exclusionary advice.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=true) suggest possible side effects, but the description fails to elaborate on behavioral traits such as whether analysis creates records or has performance implications, leaving ambiguity.

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 efficient sentence that quickly conveys the tool's purpose, although it could be slightly more structured.

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

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

With no output schema, the description should at least hint at the output format or behavior (e.g., returns a graph or list). It does not, leaving agents uncertain about what to expect.

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

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

Input schema provides full descriptions for both parameters (ci_sys_id and depth). The description adds no additional meaning beyond what the schema already conveys.

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

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

The description clearly states the specific verb 'analyze' and the resource 'downstream impact of a Configuration Item change or outage', distinguishing it from sibling tools like search_cmdb_ci or cmdb_health_dashboard.

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

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

The description implies usage for impact analysis but offers no explicit guidance on when to use this tool versus alternatives or when not to use it.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description correctly implies mutation. It adds the prerequisite condition, which is helpful, but doesn't describe consequences (e.g., irreversible changes, side effects).

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

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

The description is a single, front-loaded sentence with no extraneous words. It efficiently communicates the action and a key requirement.

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

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

For a simple one-parameter tool with annotations covering destructiveness, the description is nearly complete. It includes a prerequisite. Could mention irreversibility but not essential. No output schema needed.

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

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

The schema covers 100% of parameters with a clear description for 'sys_id'. The tool description adds no extra semantic value 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 clearly states a specific verb ('Commit') and resource ('update set'), distinct from sibling tools like 'publish_changeset' or 'complete_update_set'. It also adds a prerequisite condition.

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

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

The description provides a prerequisite (SCRIPTING_ENABLED=true) but offers no guidance on when to use this tool versus alternatives like 'publish_changeset' or 'complete_update_set'. No context on when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, indicating a safe, repeatable operation. The description adds 'useful for capacity planning' but no further behavioral details (e.g., behavior on missing tables, output format). It does not contradict annotations, so a baseline of 3 is appropriate.

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 sentence front-loaded with the verb and resource. It is concise with no wasted words, though the mention of 'time periods' could be removed or aligned with actual parameters.

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 annotations cover safety and schema describes parameters, the description is adequate for a read-only comparison tool. However, it lacks explanation of the comparison format (e.g., return structure) and the 'time periods' feature is not supported, leaving some context gaps.

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

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

Schema coverage is 100% with descriptions for both parameters ('tables' and 'query'). The description adds no new parameter insight and introduces 'time periods' which is not a parameter, potentially confusing. The description fails to add value beyond the schema.

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

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

The description clearly states the tool compares record counts across multiple tables or time periods, with a specific verb and resource. It distinguishes from sibling tools like 'get_table_record_count' which likely handles single tables, but the mention of 'time periods' is not reflected in the input schema, causing minor ambiguity.

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

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

The description notes it is 'useful for capacity planning', providing a usage context. However, it does not explicitly state when to use this tool versus alternatives like 'get_table_record_count' or 'trend_query', nor does it offer exclusions or 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?

Beyond the annotations (which show idempotentHint=true), the description adds the precondition 'requires WRITE_ENABLED=true', which is an important behavioral constraint. No contradiction with annotations.

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

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

The description is a single concise sentence that includes the essential action and a prerequisite. No fluff.

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

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

For a simple mutation tool with annotations covering idempotency, the description is sufficient. However, it lacks any mention of return values or confirmation, which would improve completeness, especially given no output schema.

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

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

The schema covers both parameters with descriptions (100% coverage). The tool description adds no additional meaning beyond what the schema already provides, earning a baseline score of 3.

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

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

The description clearly states the action ('Mark a task as complete') and includes a precondition (WRITE_ENABLED=true). It is specific enough to distinguish from sibling tools like 'close_incident' which target specific types, but it does not explicitly compare itself to them.

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

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

The description includes a functional requirement (WRITE_ENABLED=true), which provides guidance on when the tool can be used. However, it does not advise against using it for specific task types or reference alternative tools like 'close_incident'.

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 minimal behavioral context beyond annotations. It indicates a state change ('complete') but doesn't mention reversibility, triggers, or side effects. Annotations already provide idempotentHint and non-destructiveHint, so the description adds little value.

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 concise sentence with a minimal tag. It is efficient and front-loaded, though it sacrifices completeness for brevity.

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

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

For a simple action with one parameter and no output schema, the description is adequate but lacks context on what 'complete' means in the system workflow or any prerequisites. It meets minimum viability.

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

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

The schema covers the single parameter (sys_id) completely, so the description doesn't need to add parameter details. Baseline 3 is appropriate as the description offers no additional parameter semantics.

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

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

The description clearly states the action ('Mark an Update Set as complete') and the resource ('Update Set'), with the purpose being ready for migration. It distinguishes from siblings like create_update_set or export_update_set, though it doesn't explicitly differentiate.

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?

No guidance is provided on when to use this tool versus alternatives, such as preview_update_set or commit_changeset. The '[Scripting]' tag hints at context but is insufficient for clear usage direction.

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

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

The description does add non-schema context (a required prerequisite workflow, and a claim of no state-table writes), which counts for something. But 'No state-table writes are performed' combined with 'UNSUPPORTED' conflicts with annotations declaring readOnlyHint=false and a '[Write]' marker — the safety profile the agent is given is internally inconsistent and unresolved.

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 with the most important fact ('UNSUPPORTED') front-loaded; nothing is padded. The trailing '**[Write]**' marker is formatting noise rather than substance, keeping it from a 5.

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

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

For a stub/no-op tool with no output schema and fully documented params, saying 'unsupported, requires X' is close to sufficient. It still leaves the agent without a next step (what to call instead) and without resolving whether any write occurs, so it is adequate but incomplete.

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% (query, table, max_records each documented, with the 500 default stated), so the schema carries parameter meaning on its own. The description adds nothing about parameters, which is acceptable at this coverage level but no better than baseline.

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

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

The description never states what configuring offline sync actually does; its content is a negative status ('UNSUPPORTED') plus a precondition about a Mobile App Builder workflow. It does at least tell an agent the resource domain (offline configuration) and that the tool is not usable, which is more than a bare tautology, but the function itself is never described.

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?

'UNSUPPORTED' and 'requires a validated Mobile App Builder workflow' function as an explicit exclusion plus a prerequisite, which is useful routing signal. However, no sibling alternative is named — plausible substitutes like get_mobile_app_config, create_mobile_app_config, or list_mobile_app_configs are never referenced, so the agent is left to guess the replacement path.

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=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the '[Write]' tag is largely redundant. The description does add useful behavior beyond annotations: the workspace must pre-exist and existing lists are not updated. It does not explain duplicate handling, permissions, or what the response contains.

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 compact clauses: what it creates, the query mapping, the exclusions, the write marker. Front-loaded with the core action and no filler, though the trailing '[Write]' tag adds little the annotations don't already say.

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?

Five parameters with full schema descriptions and rich annotations mean the description only needs to cover intent and edge cases, which it mostly does. The one gap is return behavior for a create operation (e.g., whether a sys_id comes back), which matters for chaining.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic value by clarifying that 'query' maps to the condition column rather than being a free-form search string. Other parameters (table, title, columns, workspace_sys_id) are 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+resource ('Create a legacy sys_aw_list configuration') and scopes it to an existing Agent Workspace, which is far more precise than the tool name alone. It also distinguishes itself from UX list configuration and from updating existing lists, though it does so conceptually rather than by naming sibling tools.

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

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

Gives a clear prerequisite ('under an existing Agent Workspace') and explicit exclusions ('Does not update existing lists or configure UX lists'), which lets an agent rule out this tool for edit and UX-list cases. It stops short of naming the alternative tool an agent should use instead for those cases.

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 the important prerequisite that SCRIPTING_ENABLED=true is required, which is not present in the annotations. It also clarifies that the tool creates a persistent access rule. Since annotations already indicate mutation (readOnlyHint=false) and non-destructiveness, the description provides extra context without contradicting the structured data.

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

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

The description is a single, compact sentence that front-loads the main action ('Create a new ACL rule') and includes the crucial prerequisite in parentheses. Every word earns its place; there is no redundancy or filler.

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

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

Given the full input schema and annotations, the description provides sufficient context for an agent to understand the tool's purpose and the key requirement (SCRIPTING_ENABLED=true). It doesn't mention return values, but with no output schema defined, this is not critical. The tool is moderately complex (8 params), but the schema fills in the details, making the description adequate.

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

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

The schema covers all 8 parameters with individual descriptions (100% coverage), so the parameter semantics are well documented. The description itself adds little beyond the schema, only hinting at the use case rather than explaining any parameters. Thus, the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Create'), names the resource ('ACL rule'), and states the purpose ('to control access to a table or field'). It clearly distinguishes from sibling tools like list_acls, get_acl, and update_acl by emphasizing creation of a new rule.

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 when to use the tool (when creating a new ACL rule to manage access) and provides a critical prerequisite (SCRIPTING_ENABLED=true), but it does not explicitly mention alternatives or exclusions (e.g., 'use update_acl to modify an existing rule'). This gives clear context without full when-not guidance.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-idempotent. The description adds valuable context beyond those annotations: the automatic generation of approval requests, the WRITE_ENABLED=true requirement, and the use of the sysapproval_rule table. This gives the agent a better sense of side effects and prerequisites without contradicting the annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by the permission requirement and table detail. Every word earns its place; there is no redundancy or filler.

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

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

Given the tool's moderate complexity (7 params all documented, write operation) and the presence of annotations, the description covers the essential behavioral context: what the tool does, a key prerequisite, and the storage table. It does not describe return values, but the lack of an output schema makes that less critical. A small omission is not explicitly mentioning that 'condition' blank means always fire, but that is present in 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?

The input schema has 100% coverage with each of the 7 parameters described. The description does not provide additional parameter-level detail beyond what the schema already states (e.g., it references 'conditions' which maps to the 'condition' field, but that field is already described as 'Encoded query that determines when the rule fires'). With high schema coverage, a baseline of 3 is appropriate.

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

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

The description states a clear, specific action ('Create an approval rule') with a precise behavioral outcome ('automatically generates approval requests when a record matches given conditions'). It distinguishes this tool from siblings like approve_request or create_flow by focusing on rule creation rather than individual approval or flow automation.

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

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

The description clearly implies when to use the tool: when a user needs to set up an automated approval rule based on record conditions. It also notes a prerequisite (WRITE_ENABLED=true) and mentions the underlying table, which aids in context. However, it does not explicitly name alternatives or exclusions (e.g., 'use create_flow for complex routing'), so it stops short of a 5.

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

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

Annotations already flag it as a write (readOnlyHint=false, destructiveHint=false). The description adds real behavioral context beyond them: the rule is created INACTIVE (implying a separate activation step) and retain_references is immutable after creation. That is genuinely useful, though the openWorld/rate-limit implications are unspecified.

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 with zero filler, and the core constraint (inactive, requires existing policy) is front-loaded. The [Write] tag is a compact, useful signal.

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

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

For a 6-parameter create tool with no output schema and very low schema description coverage, the description leaves required inputs like condition and auto_rearchive unexplained. Adequate only at a minimum-viable level.

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 only 17%, so the description should compensate but it mainly restates retain_references (already documented in the schema) and says nothing about condition syntax, auto_rearchive meaning, or policy_sys_id sourcing. Minimal added value over the schema.

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

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

The description names a specific verb+resource (create an archive rule) and pins the scope (inactive, under an existing Data Management Policy). It does not explicitly differentiate from create_destroy_rule or create_cleanup_rule, so the sibling distinction is left implicit.

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 context by requiring an existing policy and notes a creation-time-only parameter, but it never says when to choose this over create_destroy_rule / create_cleanup_rule or how activation works afterward (set_archive_rule_active).

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

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

Annotations already indicate this is a write operation (readOnlyHint=false), and the description's '[Write]' adds no extra behavioral detail. It does not mention fields like asset_tag uniqueness, required versus optional parameters, or what happens on creation.

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 that is easy to parse. However, the '[Write]' marker is redundant given the annotations, adding slight noise.

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 10 parameters and no output schema, the description is too minimal. It fails to convey important context such as required fields, uniqueness constraints, or expected behavior beyond the schema information.

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 descriptions cover 100% of the parameters, so baseline is 3. The description itself adds no parameter-specific meaning, relying entirely on the schema for details.

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

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

The description clearly states 'Create a new IT asset record,' using a specific verb and resource. It distinguishes the tool from siblings like list_assets, get_asset, update_asset, and retire_asset.

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?

No guidance is provided on when to use this tool versus alternatives, no exclusions, and no prerequisites. The description simply states the action without context for selection.

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

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

Annotations already declare the operation is not read-only, not idempotent, open-world, and non-destructive. The description adds a meaningful environment prerequisite and notes ES2021 async/await support, but does not mention duplicate-name behavior, return value, or broader side effects of creating a rule.

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, front-loaded with the core action and a critical prerequisite. There is no redundant or wasted text.

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

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

For a 10-parameter creation tool with no output schema, the description covers the key enablement prerequisite but omits what is returned after creation and any duplicate or failure behavior. The rich input schema and annotations compensate partially, but the definition remains only minimally complete.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly. The description does not add parameter-level semantics beyond noting that scripts support ES2021 features, which the schema also states for the script 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?

States a specific verb ('Create') and resource ('business rule'), making its purpose clear. It does not explicitly differentiate from sibling tools such as update_business_rule or list_business_rules, but the create semantics are 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?

Adds a useful prerequisite ('requires SCRIPTING_ENABLED=true'), which helps determine whether the tool can be used. However, it gives no explicit guidance on when to use this versus update_business_rule, list_business_rules, or other rule-related tools.

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

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

The description adds the prerequisite 'requires WRITE_ENABLED=true' beyond the annotations, which already indicate this is a write operation (readOnlyHint=false). It does not disclose other behavioral traits like response format or side effects, but the annotation coverage lowers the bar.

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 sentence that is direct and front-loaded with the action and resource. It avoids unnecessary detail and earns its place.

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

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

The schema covers all parameters and annotations provide the safety profile. The description adds the key WRITE_ENABLED prerequisite. While it doesn't mention return values, the absence of an output schema and the straightforward nature of a create operation make this sufficiently complete.

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

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

The input schema has 100% coverage with descriptions for all 8 parameters. The tool description itself adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Create') and resource ('service catalog item'), making it unambiguous. It effectively distinguishes this from sibling tools like update_catalog_item and get_catalog_item.

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

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

The description provides a clear context for when to use this tool: it creates a new service catalog item and requires WRITE_ENABLED=true. It doesn't explicitly exclude alternatives, but the purpose is evident from the name and description.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the [Write] prefix and the catalog item form scope, but does not disclose additional behavioral details such as whether duplicate policies are allowed or how conditions are evaluated. With annotations present, this level is acceptable but not rich.

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 that states the verb and scope without any fluff. It is exactly as concise as it needs to be.

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 create operation with four parameters and no output schema. The description covers the core purpose but does not mention the return value or any special behavior (e.g., what happens if the catalog item ID is invalid). It is adequate but lacks additional context that would help an agent understand prerequisites or side effects.

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

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

The input schema has 100% description coverage for all four parameters, so the schema already documents each parameter's meaning. The description adds no parameter information beyond that, so it does not compensate or enhance the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Create') and resource ('UI policy') scoped to 'a catalog item form', clearly distinguishing it from the generic create_ui_policy sibling. It is immediately obvious what this tool does and how it differs from similar tools.

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

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

The description implies usage: use this when creating a UI policy specifically for a catalog item form. It provides clear context but does not explicitly name alternatives or exclusions, such as 'for other forms use create_ui_policy'. This is clear enough for most cases.

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

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description's '[Write]' prefix is redundant but consistent. However, it provides no additional behavioral context such as behavior on duplicate variable names, whether the variable is appended or replaces, or failure modes. The openWorldHint suggests possible side effects not disclosed.

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 a '[Write]' prefix that immediately signals the operation type. It is concise, with no wasted words or redundant 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?

With no output schema, the description does not explain what is returned (e.g., the sys_id of the created variable) or any error conditions. It also does not mention the dependency on an existing catalog item beyond the parameter itself. While the schema covers parameter details, the lack of return behavior and side-effect disclosure leaves the description adequate but incomplete for a write operation.

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

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

The input schema descriptions cover all six parameters with 100% coverage, including the allowed values for 'type'. The tool description adds no extra parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description uses a specific verb ('Add') and clearly identifies the resource ('form variable' to a 'service catalog item'). This distinguishes it from sibling tools like create_catalog_item, which creates the item itself, and order_catalog_item, which is a different action.

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

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

There is no guidance on when to use this tool vs alternatives, nor any prerequisites such as the catalog item already existing. The description merely states what it does, leaving the agent to infer that it should be used as a sub-action for an existing catalog item.

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

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

Annotations already indicate that the tool is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the requirement WRITE_ENABLED=true, which is a behavioral constraint beyond the annotations. However, it does not disclose other behavioral traits such as side effects (e.g., triggers notifications, creates relationships) or required permissions beyond the flag. Score 3 because it adds some value but is not comprehensive.

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 sentence that includes the essential purpose and a key prerequisite. It is concise with no unnecessary words, and the information is front-loaded. Every part earns its place, making it highly efficient for an agent 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?

Despite having 15 parameters and 2 required, the description provides no overall context about the change request lifecycle, related tools (e.g., submit_change_for_approval), or typical usage scenarios. The schema covers parameters but the description lacks completeness for a complex tool with many siblings. This incomplete context could lead to suboptimal tool selection.

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

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

Schema description coverage is 100%, meaning each parameter already has a description in the input schema. The tool description does not add any parameter-specific semantics beyond what the schema provides. Following the rule, the baseline is 3 when coverage is high, and no additional parameter information is provided in the description.

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

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

The description clearly states the verb 'create' and the resource 'change request', meeting the specific verb+resource criterion. It adds the prerequisite 'WRITE_ENABLED=true', which aids clarity. However, it does not explicitly differentiate this tool from sibling create tools (e.g., create_incident, create_problem), though the resource name is distinct. Score 4 because it is clear but lacks explicit sibling differentiation.

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

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

The description only mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives, such as update_change_request or submit_change_for_approval. There is no indication of exclusions or recommendations. This leaves the agent without context for appropriate usage, resulting in a low 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 readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description's only added behavior signal is the '[CMDB Write]' tag, which merely restates readOnlyHint=false. It says nothing about what happens when the same relationship is created twice (relevant given idempotentHint=false), whether existing relationships are affected, or what permissions are needed.

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 short sentence, front-loaded with the write tag and the core action. Nothing is bloated, though the bracketed tag is mildly redundant with the annotations and the remaining space is unused rather than efficiently spent.

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

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

For a simple three-parameter create operation with full schema coverage and annotations covering the safety profile, the description is minimally sufficient to invoke the tool. It is missing duplicate-handling behavior and any indication of what is returned (no output schema exists), which an agent would want before creating relationships.

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%: each parameter (type, child, parent) has its own description, including the 'Runs on::Runs' format example for type. The description adds no parameter meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource: creates a relationship between two CMDB Configuration Items. The '[CMDB Write]' prefix signals the domain and write nature, which helps distinguish it from the sibling list_relationships reader. It stops short of explicitly naming that sibling, but the intent 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?

There is no guidance on when to use this versus alternatives such as list_relationships or cmdb_impact_analysis, and no prerequisites (e.g. that both CIs must already exist, or that a relationship type must be valid). An agent must infer all usage conditions.

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

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

Beyond the annotations, the description explains the key behavioral safety gate: the rule is created inactive and deletes live records only after explicit activation. This meaningfully supports the destructiveHint=false annotation and clarifies the lifecycle. It does not discuss permissions, idempotency details, or the effect of optional flags such as cascade_delete.

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

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

The description is compact and front-loaded: the first sentence states what is created, and the second states the activation-dependent behavior. The only minor redundancy is the trailing [Write] marker, which repeats what the non-readOnly annotation already conveys.

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 7-parameter mutation with very low schema description coverage, the description covers the high-level activation lifecycle but leaves most inputs unexplained. An agent can understand the safety gate, but it lacks enough information to confidently choose values for condition, age_seconds, policy_sys_id, or the optional cleanup flags.

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 7 parameters and only 14% schema description coverage, the description provides no parameter-level meaning at all. It does not explain condition syntax, age_seconds semantics, policy_sys_id usage, or the optional clean_audit, cascade_delete, clean_journals, or match_field behavior beyond the one schema-described parameter.

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

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

The description gives a specific verb and resource: create an inactive Table Cleanup Rule for a Data Management Policy. It also clarifies that the rule targets live records and is not active until explicitly activated, which helps distinguish its intent from generic create tools. It does not name the closely related activation or archive/destroy siblings, so it falls short of full sibling differentiation.

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

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

The description implies the workflow context: create a cleanup rule in an inactive state for a Data Management Policy, and only activate it separately. That gives useful usage context, but it does not explicitly state when to choose this over create_archive_rule, create_destroy_rule, or when not to use it.

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

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

Annotations already indicate it is a write operation (readOnlyHint=false) and non-destructive. The description adds the key environmental requirement of SCRIPTING_ENABLED=true and the allowable script types, which are not present in annotations. This provides useful behavioral context beyond the structured metadata.

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, compact sentence that front-loads the essential purpose and includes the prerequisite inline. Every word contributes value, with no filler or redundancy.

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

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

The schema is rich, but the description omits usage context and does not mention that 'active' defaults to true, which could lead to unintentional activation. It covers the basic purpose and requirement but lacks guidance on when to choose this tool over siblings or the side effects of creation, so it is adequate but 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?

The schema has 100% coverage with individual parameter descriptions, so the description does not need to duplicate them. The parenthetical list of script types adds some context for the 'type' parameter, but overall the description adds minimal meaning beyond the schema, earning the baseline 3.

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

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

The description clearly states the action ('Create') and the resource ('client script'), and enumerates the specific script types (onLoad, onChange, onSubmit, onCellEdit). It distinguishes this tool from siblings like create_business_rule and create_script_include by being client-script-specific.

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 by naming the resource type, and mentions a prerequisite (SCRIPTING_ENABLED=true), but does not explicitly state when to use it versus alternatives like create_ui_policy or update_client_script. No exclusions or alternative recommendations are provided, leaving usage guidance primarily implicit.

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

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

Annotations already cover readOnly=false and destructive=false, yet the description adds genuinely non-obvious behavior: the WRITE_ENABLED=true gate and the platform quirk that implementation_statement is dictionary-mandatory but silently blanked by the REST layer if omitted. That is exactly the context annotations cannot express.

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

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

Two sentences, purpose first, then the single highest-risk pitfall, then a bolded write-gate flag. Dense and front-loaded with essentially no padding, though the banner could be moved earlier if it is the primary gate.

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

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

For a mutation tool with no output schema and a low-coverage 8-parameter schema, the description covers the one dramatic trap well but leaves an agent guessing about most field semantics and about what a successful response looks like. Adequate but clearly incomplete.

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 25% and 8 parameters exist, so the description must compensate and does not. It elaborates only on implementation_statement (already described in the schema) and says nothing about owner, profile, category, frequency, key_control, or what `name` accepts.

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 Compliance Control) and names the backing table sn_compliance_control, which lets an agent place it among the GRC write tools. It does not explicitly contrast with siblings like update_compliance_control or create_compliance_policy, though the name does most of that work.

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 write-flag banner signals a precondition and the 'create' verb implies when it applies, but there is no statement of when to use this rather than update_compliance_control or create_compliance_policy, nor any prerequisites beyond WRITE_ENABLED.

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

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

Goes well beyond the annotations by disclosing that the platform silently defaults kb_knowledge_base, approval_method and article_template rather than failing, and names the actual default values. It also surfaces the WRITE_ENABLED=true gate, which is exactly the kind of operational constraint an agent needs before attempting 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?

Two sentences plus a bracketed write-gate tag; the core action comes first, then the highest-risk gotcha (silent defaults), then the security constraint. Nothing is redundant with the schema and no sentence could be dropped without losing 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 9-parameter mutation with no output schema, the description covers the write gate and the tricky defaulting behaviour, which are the main failure modes. It does not state what a successful create returns (e.g. the new sys_id), which would be useful for chaining into update_compliance_policy.

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 56% schema coverage, the description compensates by explaining the defaulting semantics of the three most error-prone optional parameters and their concrete default values. It leaves owner, owning_group, category, policy_category and description entirely to the schema, so coverage is good but not complete.

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?

Names a specific verb and resource and anchors it to the underlying table (sn_compliance_policy), so an agent can distinguish it from list_compliance_policies, get_compliance_policy and update_compliance_policy by verb alone. It stops short of routing the agent away from near-neighbours like create_compliance_control, but the purpose 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?

Gives a conditional rule for the three dictionary-mandatory fields (omit safely vs. pass explicitly when a specific KB/approval method/template is needed) and flags the WRITE_ENABLED prerequisite. It offers no guidance on when to create versus update an existing policy, nor any prerequisite/ordering advice relative to create_compliance_control.

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

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

Annotations already indicate that this is a write operation (readOnlyHint=false), non-destructive, and non-idempotent. The description adds the permission requirement 'WRITE_ENABLED=true', which is useful but does not significantly expand on behavioral traits beyond what annotations provide.

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

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

The description is a single, short sentence that conveys the purpose and a key prerequisite with no unnecessary words. It is perfectly concise and front-loaded with essential information.

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

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

Given the tool has 9 parameters and no output schema, the description is minimal. It covers the basic purpose and a permission requirement but lacks details on return values, typical usage patterns, or how it fits with other CSM tools. It is adequate but not comprehensive.

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%, meaning all 9 parameters have descriptions in the schema. The tool description does not add any additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Create' and the resource 'Customer Service case', distinguishing it from sibling tools like get_csm_case, update_csm_case, and close_csm_case. The tool name and description align perfectly.

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

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

The description explicitly mentions a prerequisite condition 'requires WRITE_ENABLED=true', which guides the agent on when to use this tool. However, it does not provide explicit guidance on when not to use it or compare it to alternative tools.

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

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

Annotations indicate a non-read-only, non-destructive write operation. The description adds the key prerequisite of WRITE_ENABLED=true, which is valuable context beyond what annotations provide. This is a meaningful behavioral constraint for the agent.

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

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

The description is a single sentence with no extraneous words. The verb and resource are front-loaded, and the requirement is a parenthetical addition that doesn't clutter the main purpose.

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

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

For a create operation with comprehensive schema descriptions and annotations, this description provides the essential context: what it does and a required permission. No output schema exists, so return value details aren't expected. The description is complete for its purpose.

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

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

Schema coverage is 100% with descriptive comments for all 4 parameters. The description doesn't add param-specific details, but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states 'Create a new Performance Analytics dashboard', specifying the action, resource, and domain. It distinguishes itself from sibling tools like update_dashboard and list_pa_dashboards, and the parenthetical requirement adds precision.

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

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

The description provides a clear context for use (creating dashboards) and includes a prerequisite (WRITE_ENABLED=true). However, it does not explicitly name alternatives or state when not to use it, but the context is strong enough for a create tool.

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

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

Annotations already cover the mutation profile: readOnly=false, destructive=false, idempotent=false, openWorld=true. The description adds useful context beyond that: the created policy is inactive, and policies already existing for the table are rejected. The rejection wording is somewhat ambiguous, but the added behavioral context is meaningful.

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

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

The description is two short sentences and front-loads the main action. The "[Write]" tag is redundant with annotations but does not add significant noise.

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 mutation tool with three parameters, no output schema, and no schema descriptions. The description gives the core action and one constraint, but it omits what name/table should contain, how "inactive" affects use, and what happens on rejection, which is not enough for reliable invocation.

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

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

Schema description coverage is 0%, so the description must explain the three parameters. It only indirectly references the table parameter and gives no meaning for name or description, leaving required parameters effectively undocumented.

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 an inactive Data Management Policy." It clearly distinguishes creation from sibling listing/getting tools such as list_data_management_policies and get_data_management_policy, though it does not name those siblings explicitly.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives, prerequisites, or conditions for creation. The note that existing policies for the table are rejected is a behavioral constraint rather than 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 real behavior beyond the annotations: the created rule is inactive by default, so nothing takes effect until it is later activated, and retention_days has a hard minimum of one day. Annotations cover the write/open-world/idempotency profile, so this additional context is the valuable part. It doesn't say what happens if archive_rule_sys_id is invalid or what the response contains.

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, front-loaded sentences with the key fact (inactive) first. The retention_days sentence duplicates the schema's minimum constraint, which is minor redundancy but still useful as a quick-read guard.

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

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

For a mutation tool with no output schema and 0% parameter documentation, the description covers purpose and the inactive-by-default outcome but leaves the parameter contract and the activation follow-up largely implicit. Adequate to identify the tool, thin for calling it correctly.

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