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

Beyond the annotations, the description discloses that this inserts a sysapproval_approver row and requires WRITE_ENABLED=true. This is useful operational context. It does not mention potential side effects like notifications or duplicate handling, but the core write behavior is clearly 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 two sentences with no wasted words. The primary action and data effect are front-loaded, and the prerequisite is cleanly separated. Every sentence contributes useful information.

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

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

For a simple three-parameter write operation, the schema, annotations, and description together cover the inputs, the required precondition, and the data effect. The main minor gap is not explaining what happens after the insertion, such as whether the approver is notified or whether duplicates are prevented.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters. The description adds no meaningful parameter-level detail beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Add an ad-hoc approver to an in-flight approval on a record.' It also names the underlying data effect (inserts a sysapproval_approver row), which clearly distinguishes it from sibling approval tools like approve_request or create_approval_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 gives clear context by requiring an 'in-flight approval' and states the prerequisite 'Requires WRITE_ENABLED=true'. It does not explicitly list alternatives or when-not-to-use, but the context is specific enough to route an agent correctly.

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?

The description adds the specific 'Requires WRITE_ENABLED=true' requirement, which is not captured in the annotations. Since annotations already signal readOnlyHint=false and idempotentHint=false, the description goes beyond that by disclosing an operational prerequisite. It does not contradict the annotations and provides meaningful 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?

A single, concise sentence that immediately states the core action and the critical prerequisite. No filler or redundant information. The most important detail is front-loaded.

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

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

For a simple add operation with no output schema, the description covers the essential information: the action, the target table, and a required environment flag. It does not describe return values or side effects, but these are not explicitly required here. The description is adequate for the tool's simplicity.

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

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

Schema description coverage is 100%, with each parameter having a clear description (e.g., 'sys_id of the roster'). The description adds no additional 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?

Clearly states the action (add), the resource (member to an on-call roster), and even names the underlying table (cmn_rota_member). This is a specific verb+resource description that distinguishes it from sibling tools like create_rota_schedule or create_on_call_override.

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 no guidance on when to use this tool versus alternatives, nor any contextual conditions beyond the WRITE_ENABLED requirement. It does not mention scenarios or prerequisites for calling it, leaving the agent to infer usage from the name alone.

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

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

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 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?

The description describes a mutating operation ('advance', 'next state'), but the annotations declare readOnlyHint=true, which indicates a read-only operation. This is a direct contradiction that could mislead an agent about the tool's side effects. The description provides no further behavioral context beyond the misleading advance action.

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

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

The description is concise, consisting of two sentences. It includes a useful prerequisite (WRITE_ENABLED=true) and a reference to ServiceNow HRSD parity, which adds context without excess verbosity. The structure is front-loaded with the action.

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 lacks essential context for a mutation tool, such as return value, side effects beyond state change, or any prerequisites beyond WRITE_ENABLED. Critically, it fails to reconcile the contradiction with the readOnlyHint annotation, leaving the agent with incomplete and inconsistent 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?

The input schema covers all three parameters with descriptions (case, state, work_notes), achieving 100% schema coverage. The description does not add additional parameter semantics, but with high 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 identifies the action as 'advance' an HR case to its next state/stage, naming the resource and target table (sn_hr_core_case). It conveys the core function effectively, though it doesn't explicitly differentiate from sibling tools like close_hr_case or update_hr_case, which are also possible state-changing operations.

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 stating the operation ('advance to next state'), and the 'Parity with ServiceNow HRSD' reference gives some context, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention exclusions or conditions. Usage is only implied, 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?

The description discloses significant behavior beyond the readOnlyHint and openWorldHint annotations: no 1000-row truncation, automatic average resolution time for task tables, pre-formatted duration fields, and a detailed return structure. This gives the agent a strong sense of what to expect.

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

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

Every sentence earns its place: purpose, key differentiator, usage example, special behavior, output format, and read-only status. It is dense but not verbose, and the most important information is front-loaded.

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

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

For a tool with 9 parameters and no output schema, the description explains the return components (stats table, rows, chart, summary) and critical edge cases. It covers the main use case, performance characteristics, and automatic behaviors, making it complete for agent selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable semantic context for avg_fields/sum_fields (e.g., task tables auto-include average resolution time, duration fields come pre-formatted), which helps the agent use these parameters effectively without repeating schema info.

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 defines the tool as a server-side aggregate report that groups by a field and returns per-group counts plus aggregates in a single query. It explicitly distinguishes from raw record listing ('Do NOT list raw records for this') and uses a specific verb+resource structure.

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

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

It provides clear guidance on when to use this tool ('the right tool for a periodic summary') and explicitly warns against using it for raw records. However, it does not name specific alternative tools, so it lacks the 'alternatives' component for a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the 'AI-powered' and 'semantic' aspects, which hint at non-deterministic or relevance-based behavior, but does not disclose other traits such as result formatting, pagination, or potential latency. The added context is minimal but not contradictory.

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, focused sentence that front-loads the main action and scope. No filler or redundant information, making it highly concise and well-structured.

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

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

For a search tool with only 3 parameters and no output schema, the description is sufficiently complete to understand its purpose and scope. It does not mention return format or pagination, but the lack of output schema makes some additional detail desirable, though not critical for a search operation.

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

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

Schema coverage is 100% with all parameter descriptions present, so the schema already documents the parameters. The description does not add additional parameter semantics beyond what the schema provides, maintaining the baseline of 3.

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

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

The description clearly states the action (search) and the specific resource set (KB, catalog, incidents), which distinguishes it from sibling tools like search_knowledge or search_catalog that target a single source. It is a specific verb+resource combination with no 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 implies use for cross-source semantic search but does not explicitly state when to use it over alternatives or when not to use it. There is no mention of exclusions or alternative tool comparisons, so the guidance is limited to the implied scope.

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 and open-world behavior, so the bar is lower. The description adds the three analysis dimensions but does not disclose output format, whether all dimensions are always calculated, or how 'stale' is defined beyond the parameter hint. 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?

A single sentence effectively front-loads the verb, target resource, and key dimensions. There is no filler or redundancy.

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

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

Given the rich schema and read-only annotations, the description is largely sufficient for tool selection. However, it does not describe the return value or output structure, which would be helpful since no output schema is provided.

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

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

Schema coverage is 100%, with all three parameters described, so the baseline is 3. The description adds meaningful framing by linking completeness and stale records to the parameters, but it does not provide extra syntax, defaults, or examples 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 analyses data quality for a table and lists the three concrete dimensions: completeness, duplicates, stale records. This distinguishes it from sibling tools such as check_table_completeness or get_table_record_count.

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 use when an overall data quality assessment is needed, but it does not explicitly state when not to use this tool or mention alternatives like check_table_completeness for completeness-only checks. There is no exclusion guidance.

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

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

Annotations already indicate readOnly=false and destructive=false. The description adds useful behavior context: the requirement that WRITE_ENABLED=true must be set, and the condition that the request must be pending. This goes beyond the structured data and helps the agent understand prerequisites and state constraints.

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

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

The description is a single, well-structured sentence with a parenthetical requirement. It front-loads the action and contains no unnecessary words. Every element 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 tool with annotations and full schema coverage, the description is largely sufficient. It states the action, the prerequisite, and the target state. It does not describe return values or failure conditions, but these are less critical for a straightforward approval action.

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

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

Schema coverage is 100% with clear descriptions for sys_id and comments. The tool description does not augment parameter meanings, so the schema carries the full burden. 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 'Approve' with a clear resource ('a pending approval request'), which clearly distinguishes it from sibling tools like 'reject_request' and 'list_approvals'. The purpose is immediately obvious and unambiguous.

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

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

The description implies the tool is used for approving approval requests, but it does not explicitly contrast with alternatives such as 'reject_request' or state when not to use it. The WRITE_ENABLED requirement provides a constraint but no guidance on choosing between 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 a write operation (readOnlyHint=false). The description adds the table name and the WRITE_ENABLED requirement, going beyond annotations. It does not describe side effects (e.g., whether it creates a new relation or updates), but the basic mutating nature is clear.

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 concise sentence that leads with the action, names the resources, and includes a critical prerequisite. 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?

The description explains the action and a requirement, but omits what happens on success (e.g., return value) and whether the operation is additive or replaces existing associations. Given no output schema, these details are missing.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds no extra meaning beyond the schema, aligning with the baseline for high coverage.

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

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

The description uses a specific verb ('Attach') and names the exact resources ('user criteria to a catalog item') plus the underlying table (sc_cat_item_user_criteria_mtom). It clearly distinguishes from creating a new criteria (create_user_criteria) and other catalog operations.

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

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

It explicitly states a prerequisite ('Requires WRITE_ENABLED=true'), which is useful guidance. It doesn't name alternatives or when-not-to-use, but the tool's specificity makes the use case unambiguous.

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

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

The description explicitly states the tool can execute POST, PATCH, and DELETE methods, but the annotations declare readOnlyHint=true. This is a direct contradiction: a read-only tool cannot perform write operations. The description and annotations are irreconcilable, severely undermining trust and safety.

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 long, front-loaded with the core purpose, and includes only essential details (method, URL, body, max operations). No wasted words 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?

Given the tool's complexity (batch operations with multiple HTTP methods), the description covers the basics but omits important behavioral details such as response format, ordering guarantees, partial failure behavior, and correlation via operation IDs (which the schema partially addresses). The annotation contradiction further exacerbates the overall incompleteness.

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

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

The schema provides 100% coverage with detailed descriptions for operations, id, method, url, and body. The description adds the 50-operation limit and mentions optional body, but these are already captured in the schema via maxItems and the body property. The description adds minimal 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 executes multiple ServiceNow REST API operations in a single HTTP call, which is a specific verb+resource combination. It distinguishes itself from the many individual operation tools in the sibling list by focusing on batching.

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 this tool by noting it reduces round-trips by 50-70% and has a maximum of 50 operations per batch. This gives clear context for batching multiple operations but does not explicitly name alternatives 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?

The description discloses behaviors beyond annotations: it returns a rollback_token, tracks all created sys_ids, deletes already-created records on mid-way failure when rollback_on_error=true, supports dry_run, and requires WRITE_ENABLED=true. These are not captured in the annotations.

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

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

Three concise sentences, front-loaded with the primary action. No wasted words; covers purpose, rollback semantics, and prerequisites 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?

Given no output schema, the description mentions the key return elements (created sys_ids and rollback_token) and covers essential behaviors. Missing details like exact response structure or batch size limits, but overall sufficient for a bulk create operation.

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

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

Schema coverage is 100%, and the description adds minimal parameter-specific meaning beyond restating the behaviors of rollback_on_error and dry_run. The schema already describes each parameter, so the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's function: bulk-creating records in a single table, distinguishing it from single-record create tools like create_record. It also mentions key outputs (sys_id tracking, rollback_token) and features (dry_run).

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 phrase 'Create many records in one table in a single call' implies when to use this over single-record tools. It also specifies a prerequisite (WRITE_ENABLED=true) and describes rollback behavior when rollback_on_error is set, but doesn't explicitly name alternative tools for single-record creation.

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 it is a write operation (readOnlyHint=false) and not destructive. The description adds no additional behavioral context, such as whether existing values are overwritten, how partial failures are handled, or permission requirements. The [Write] tag is redundant with the annotation.

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

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

The description is a single, front-loaded sentence that effectively communicates the tool's purpose without unnecessary words. It earns its place and is easily scannable.

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

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

The tool is a batch write operation with no output schema, and the description does not mention return values, error behavior, atomicity, or permission requirements. For a one-parameter tool with good annotations, this is adequate but leaves gaps that could affect correct invocation and result interpretation.

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

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

The input schema already describes the 'properties' parameter in detail ('Array of {name, value, description?} objects'), and schema coverage is 100%. The description adds no additional parameter meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Create or update'), the resource ('system properties'), and the batch scope ('multiple... in a single operation'), distinguishing it from single-property tools like set_system_property. The [Write] tag reinforces the mutation intent.

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 batch usage with 'multiple' and 'single operation,' but provides no explicit guidance on when to prefer this tool over alternatives such as set_system_property for single updates or bulk_get_properties for reads. No exclusions or alternatives are mentioned.

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

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

Annotations already declare read-only/open-world hints; the description adds non-obvious context about the Table API mechanism and the PI endpoint limitation. It does not contradict annotations and reveals that the result is a suggestion, not a persistent update.

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

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

Two focused sentences; the first states the purpose, the second adds an important limitation/alternative. No redundant 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 two-parameter read-only suggestion tool with annotations, the description provides sufficient context including mechanism, output fields, and an important PI limitation. It could slightly improve by naming the exact sibling alternative or return structure, but current coverage is strong.

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% parameter coverage, so the baseline is 3. The main description does not add parameter-specific details beyond what the schema already provides; it only reinforces that short_description drives the heuristic.

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

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

The description opens with a specific verb ('Suggest') and clearly identifies the resource (incident) and outputs (category, assignment group, priority). The phrase 'by analysing similar resolved incidents (Table API)' distinguishes it from sibling ML/PI-based tools by naming the mechanism.

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

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

It gives clear context that this is a Table API heuristic and explicitly states that PI has no public REST prediction endpoint, directing model-based needs to PI on-record. It does not name sibling tools like ml_auto_categorize, but the boundary is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate that. It adds value by disclosing the conditional execution (attempts a skill, else returns employee + service context) and the parity with ServiceNow HRSD. This goes beyond annotations and is useful, though it doesn't detail the exact 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?

Two sentences with no wasted words. The first sentence front-loads the primary action and fallback behavior, while the second adds parity context. It is concise and structured effectively, though the parity reference could be seen as mildly extraneous.

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?

Without an output schema, the description must clarify what the tool returns, but it doesn't. It mentions 'return the employee + service context' as a fallback, but does not specify what happens when the skill is available (presumably an eligibility result). This ambiguity leaves an agent uncertain about the exact return format, which is a significant gap for a simple 2-parameter tool.

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

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

Schema description coverage is 100%, with both parameters clearly documented ('Employee sys_id, user_name, or email' and 'HR service sys_id or name'). The description adds no additional semantics 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 action ('Check') and the resource ('eligibility for an HR service/policy'), and it distinguishes from HR case creation/management siblings by focusing on eligibility evaluation. The mention of a skill and fallback adds specificity. It could be more explicit about what 'eligibility' means, but overall the purpose is clear.

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

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

The description implies the tool is used when an eligibility check is needed, and it mentions a conditional path ('via skill when available'). However, it does not explicitly contrast with alternatives like get_hr_profile or list_hr_services, or state when not to use it. The guidance is present but 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 declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a read-only, potentially incomplete operation. The description adds that it returns percentages per field, which is useful context. However, it does not disclose behavioral details such as sampling methodology, impact of sample_size, or limitations like openWorldHint implying results may not cover all records.

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 front-loads the primary action and output. It earns its place with no redundancy, making it highly 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?

Without an output schema, the description provides essential return information (percentage of non-empty values per field). It mentions the input type (ServiceNow table) and the analysis focus. However, it omits potential edge-case behavior or calculation details (e.g., how empty strings are treated), which would be valuable for full completeness. Still, it is sufficiently complete for a read-only analysis tool with strong schema coverage.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description does not add additional meaning beyond the schema; it does not explain how 'sample_size' or 'query' affect the analysis results. Baseline 3 is appropriate when the schema carries the full parameter documentation.

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

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

The description clearly states the tool's function: 'Analyze data quality and field completeness for a ServiceNow table — returns percentage of non-empty values per field'. It uses specific verbs ('Analyze', 'returns') and identifies the resource ('ServiceNow table'), distinguishing it from siblings like analyze_data_quality, get_table_record_count, and query_records.

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

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

The description implies usage for data quality analysis, but does not explicitly state when to use this tool versus alternatives. No mention of exclusions or comparison with other analysis tools like analyze_data_quality or query_records. Usage is implied by the purpose, but lacks direct 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 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 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?

The annotation readOnlyHint=true already indicates a safe read operation. The description adds valuable behavioral context with 'in-memory grouping', revealing that the tool scans a limited set and groups in memory rather than performing a database-level query. This goes beyond the annotations without contradicting them.

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

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

The description is a single, front-loaded sentence that immediately conveys the action and method. 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?

The tool is simple with only optional parameters and read-only behavior. Given the annotations and full schema coverage, the description sufficiently covers the core purpose, though it doesn't describe the return format. It's still adequate for a basic discovery 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?

All parameters are fully described in the input schema (100% coverage), so the description adds minimal new info about parameters. It does imply match_fields with 'specified fields' and limit with 'in-memory', but the schema already covers these.

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

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

The description uses a specific verb ('Find') and resource ('duplicate CIs'), clearly distinguishing from sibling tools like cmdb_find_orphans and cmdb_find_stale. The phrase 'by matching on specified fields' further clarifies the tool's 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 gives a clear context (finding duplicates) but does not explicitly state when to use this tool over alternatives like search_cmdb_ci or cmdb_reconcile, nor does it mention any exclusions.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the table-specific scoping to cmdb_rel_ci but doesn't disclose behavior like how orphan detection works (e.g., does it consider relationship direction or only direct relationships). Still, given the annotations, it provides baseline 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, focused sentence that communicates the tool's purpose without unnecessary words. It is appropriately concise and front-loaded.

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

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

The tool is a simple read-only query with two optional parameters, and the schema and annotations cover the basics. However, the description lacks usage guidance, examples, or any mention of what the output looks like. It is minimally complete but leaves some ambiguity about the exact definition of 'orphan' in relation to relationship 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?

The input schema already describes both parameters (limit and ci_class) with clear descriptions, achieving 100% coverage. The description does not add any additional parameter semantics, so the baseline score 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 the specific verb 'Find' and identifies the exact resource: CIs with no relationships in the cmdb_rel_ci table. This clearly distinguishes it from sibling tools like cmdb_find_duplicates and cmdb_find_stale, which target different criteria.

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 about when to use this tool versus alternative CMDB discovery tools such as cmdb_find_duplicates or cmdb_reconcile. The description only states what the tool does, not when it should be selected.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, which cover the safety profile. The description adds the 'still operational' filter and the time-based condition, but does not disclose return format, pagination behavior, or interpretation of 'operational.' With annotations present, this 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?

A single, well-structured sentence that front-loads the verb and resource, then clarifies the condition. Every word earns its place; no fluff 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 read-only query tool with well-documented optional parameters and no output schema, the description covers the core functionality. It could benefit from addressing what 'operational' means or how results are ordered, but overall it is sufficient for a simple find operation.

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

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

Schema coverage is 100%—all three parameters (limit, ci_class, days_threshold) have descriptions, so the schema does the heavy lifting. The description adds marginal value by implying the days_threshold concept, but does not enhance parameter understanding beyond the schema.

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

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

The description uses a specific verb ('Find') and resource ('CIs') with a clear condition ('not updated within a given number of days that are still operational'). It distinguishes itself from sibling tools like cmdb_find_duplicates and cmdb_find_orphans by targeting stale but operational configuration items.

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

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

Usage context is implied through the description—'find CIs not updated...' suggests when to use it, but there is no explicit guidance on when not to use it or how it compares to alternatives like cmdb_find_duplicates or cmdb_reconcile. No exclusions or alternative tool references are 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 and openWorldHint, so the safety profile is covered. The description adds useful selection semantics (operational CIs with relationships but no application service), but does not disclose return shape, pagination, or any additional operational behavior beyond what annotations and the description's predicate imply.

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

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

Two sentences with no filler. The core purpose is front-loaded, and the ServiceNow parity reference is a useful compact anchor for familiar users without bloating the description.

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

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

For a read-only lookup tool with fully documented parameters and no required arguments, the description covers the domain intent and selection criteria well. It could be even more complete by stating the return format or default limit behavior, but those are also covered by the schema and the tool's name.

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%, and both parameters (limit and ci_class) are already meaningfully described in the schema. The tool description adds no extra parameter-level meaning, 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?

States a specific verb ('Find'), resource ('operational CIs'), and precise selection condition ('have relationships but belong to no application service / mapping gaps'). This clearly distinguishes it from related CMDB sibling tools such as cmdb_find_orphans and cmdb_find_stale at a glance.

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 use context: call this when you need to surface CIs that are related but not mapped to an application service. It stops short of explicitly naming alternatives or saying when not to use it, but the mapping-gap framing is sufficient for an agent to route correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only safety is covered. The description adds that it focuses on completeness metrics for server and network CIs, which is useful context. However, it does not disclose any additional behavioral traits such as return format, pagination, or required permissions, so it only partially extends 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?

The description is a single, concise sentence that front-loads the verb and resource. It contains no fluff or redundant information, earning the highest score.

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

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

Given the tool has no parameters, no output schema, and read-only annotations, the description provides adequate context for a simple getter. It tells the agent what metric to expect (completeness) and for which CIs (server and network). It doesn't elaborate on the return format, but for such a simple tool, this is sufficient.

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

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

The input schema has zero parameters, so there is no parameter semantics to explain. The baseline is 4 for 0-parameter tools. The description appropriately doesn't attempt to add parameter details.

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

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

The description clearly states the tool retrieves CMDB data quality metrics, specifically completeness of server and network CI data. This gives a specific verb+resource scope. However, it does not explicitly distinguish from sibling tools like analyze_data_quality or check_table_completeness, though the focus on server/network CI data provides some 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?

No guidance is provided about when to use this tool versus alternatives. There is no mention of exclusions or preferred scenarios. The description simply states what it does without context on choosing it over similar CMDB-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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds the 'downstream impact' and 'change or outage' context, which is more specific than the raw annotation. However, it does not disclose details about how the analysis is performed (e.g., traversal depth, whether results are approximate, or if it reflects current state vs. simulated changes). With annotations covering the read-only nature, a score 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, tightly written sentence that immediately conveys the core purpose. It is front-loaded with the key verb and resource, and contains no filler 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?

The description is adequate for a simple tool with only two parameters and read-only annotations. However, it lacks information about the return format or what 'impact' concretely means (e.g., affected CI list, risk score). Given the absence of an output schema, the description could be more complete, but the core use case is still clear.

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%: both 'ci_sys_id' and 'depth' have descriptive names and descriptions in the schema. The tool description adds no additional parameter context beyond what the schema already provides, 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 clearly states the tool's function: 'Analyze the downstream impact of a Configuration Item change or outage' with a specific verb ('Analyze'), a clear resource ('Configuration Item'), and a well-defined scope ('downstream impact'). It distinguishes itself from sibling tools like 'get_cmdb_ci' (which retrieves a single CI) and 'list_relationships' (which lists raw relationships) by focusing on impact assessment.

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: when analyzing the downstream impact of a CI change or outage. It does not explicitly exclude or recommend against alternatives, but the specificity of the scenario (change/outage) gives sufficient guidance. No explicit alternatives are mentioned, so it does not reach 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 declare readOnlyHint=true, but the description describes mutating actions (merge, retire, remove) and requires CMDB_WRITE_ENABLED, directly contradicting the annotation. This is a serious inconsistency, and the description does nothing to resolve or explain it. Without the contradiction, it would disclose some behavior, but the contradiction warrants the lowest score.

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

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

The description is two concise sentences, front-loading the core purpose and actions. It includes a key prerequisite and a feature note (dry_run) without unnecessary detail. Every word earns its place.

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

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

The tool has no output schema, and the description does not explain return values, what happens after merge/retire/remove, or whether actions are reversible. While the core purpose and parameters are covered, the missing behavioral details and the annotation contradiction leave it incomplete for a mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents action, targets, and dry_run. The description adds minimal extra value, only reiterating dry_run mode and the write requirement. This aligns with the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool acts on duplicate, stale, or orphan CIs with specific actions (merge, retire, remove). It distinguishes itself from sibling tools like cmdb_find_duplicates, cmdb_find_orphans, and cmdb_find_stale, which likely only identify issues, while this tool acts on 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 provides clear context: it is for reconciliation actions on CIs, and it states a prerequisite (requires CMDB_WRITE_ENABLED). It also mentions dry_run mode for safe previewing. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds context about the reverse-lookup nature and the underlying association table, which is useful. It does not describe return format, pagination, or error behavior, but for a read-only lookup the annotation coverage is sufficient. 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 two sentences with zero filler. The primary purpose is front-loaded in the first sentence, and the second sentence adds a useful reference to the ServiceNow API for context. Every word 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 reverse-lookup tool with read-only annotations, the description is adequate but not complete. It doesn't explain what the return value looks like (no output schema exists), nor does it clarify how to handle cases where both ci and ci_name are provided or neither. It also omits any mention of default behavior for limit, which is in the schema but not reinforced. Given the tool's low complexity, this is acceptable but leaves room for improvement.

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

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

Schema description coverage is 100%, so all parameters (ci, limit, ci_name) are already documented in the schema. The description does not add any additional meaning beyond what the schema provides—for example, it doesn't clarify the relationship between ci and ci_name or whether both can be used. Per the baseline, a score of 3 is appropriate when the schema handles parameter documentation.

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

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

The description clearly states the tool's purpose: a reverse lookup to find which application services contain a given CI/server. It names the underlying table (svc_ci_assoc) and references parity with a ServiceNow API, giving a specific and unambiguous action. However, it doesn't explicitly distinguish itself from sibling tools like list_application_services, which also deal with services, so it misses an opportunity for 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 a use case (when you have a CI and want its services) but provides no explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it, what the sibling list_application_services does differently, or any prerequisites. The parity note hints at a standard behavior but doesn't serve as usage guidance.

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

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

Annotations already establish readOnlyHint=false and destructiveHint=false, so the description need not repeat these. It adds the prerequisite that SCRIPTING_ENABLED=true, which is useful operational context. However, it does not disclose what happens when committing, whether the operation is reversible, or any 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 extremely concise, using only nine words. Every word contributes to the core message. However, the brevity leaves out essential context, but it is still efficient and front-loaded.

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

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

With no output schema, the description should explain the commit behavior, prerequisites beyond the single mentioned one, and potential consequences. It only states the action and one prerequisite, leaving the agent with insufficient understanding of how the commit works and how it differs from similar tools.

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 'sys_id' with 100% coverage, including its description. The description adds no additional meaning to the parameter, 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 the specific verb 'Commit' with the resource 'update set', clearly indicating the action. However, it does not distinguish from sibling tools like 'publish_changeset' or 'complete_update_set' which may perform similar operations.

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. The only additional information is a prerequisite (SCRIPTING_ENABLED=true), which is not guidance for choosing the tool. It lacks any mention of typical use cases or exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds useful context about optional query scoping and the ability to compare either record counts or property values. However, it does not disclose prerequisites like what 'configured' instances entail or what happens when both optional parameters are omitted.

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 tight and front-loaded: two sentences that immediately state the action and purpose. There is no fluff, and every word contributes to understanding.

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

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

The tool has 5 parameters and no output schema, so the description needs to cover the main use cases. It does that, but it lacks a description of the return format or behavior when neither table nor property is specified. The mention of 'configured' instances is also vague, leaving a small but meaningful gap in completeness.

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

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

The input schema has 100% description coverage, so parameters are already documented. The description adds a bit of context by mapping 'table', 'query', and 'property' to the comparison types, but this is redundant with the schema descriptions and does not provide significant additional meaning.

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

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

The description uses a specific verb 'Compare' and a clear resource 'two configured ServiceNow instances', and explicitly states what is compared (record counts and/or system property values). This distinguishes it from sibling tools like compare_record_counts or get_system_property, which operate on a single instance or a different scope.

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

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

The description provides a clear use case ('dev→prod drift detection and governance') and implies cross-instance comparison, which differentiates it from sibling tools. However, it does not explicitly state when not to use it or mention alternatives, though the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds the multi-table scope but does not disclose return format, potential performance implications, or permission requirements. With annotations covering the main safety aspect, the description adds some value but not rich 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?

The description is a single sentence, front-loading the main action and keeping unnecessary words to a minimum. The dash clause 'useful for capacity planning' is a brief, useful context. However, the phrase 'time periods' introduces ambiguity without explanation, slightly undermining structure clarity.

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

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

The tool has no output schema, so the description should explain the return value(s), but it only states the action and a use case. The schema covers parameters well and annotations handle safety, but the missing return format is a significant gap for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%: both tables and query have clear descriptions in the schema. The tool description does not add any additional parameter-level detail beyond the schema; the mention of time periods is not explicitly tied to a parameter, so it adds no semantic 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?

The description clearly states the tool compares record counts across multiple ServiceNow tables or time periods, with a specific verb and resource. It distinguishes from siblings like get_table_record_count, though the mention of time periods without a schema parameter creates slight 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 phrase 'useful for capacity planning' provides a use case but no explicit guidance on when to use this tool versus alternatives such as get_table_record_count or query_records. There are no exclusions or alternative recommendations, so usage is implied rather than 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?

The description adds the prerequisite 'Requires WRITE_ENABLED=true', which is beyond the annotations (readOnlyHint=false already indicates a write). It does not describe side effects or reversibility, but the annotations already signal it is not destructive. It provides some value but remains minimal.

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 captures the core action and a critical prerequisite. There is no filler, and it is easy to parse quickly.

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 close-operation tool, the description covers the essential purpose and a key requirement. It does not explain return values, but no output schema exists, and the agent can infer success from typical tool behavior. It is sufficiently complete for a straightforward mutation.

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

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

The input schema covers all parameters with descriptions (100% coverage), so the description adds no extra parameter context. It does not explain the default state value or the purpose of close_notes beyond what the schema already states, 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 action ('Close'), the specific resource ('catalog fulfillment task (sc_task)'), and the resulting state ('as complete'). It differentiates from generic tools like complete_task by explicitly naming sc_task, so an agent can distinguish it.

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

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

The description implies usage for catalog fulfillment tasks by naming the table (sc_task), which distinguishes it from generic task completion. However, it does not explicitly mention alternatives or exclusions (e.g., 'use complete_task for non-catalog tasks'), leaving some inference to the agent.

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

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

The description adds the WRITE_ENABLED=true prerequisite, which is beyond what the annotations state, but it does not disclose side effects, irreversibility, or what happens after completion. Annotations already signal readOnlyHint=false and idempotentHint=false, so the added behavioral context is minimal yet not contradictory.

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 prerequisite with zero unnecessary words. It is appropriately sized for a simple tool.

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

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

For a simple mutating task with one required parameter and good annotations, the description covers the purpose and the key prerequisite. It does not explain return values or error conditions, but the schema and annotations fill most gaps, making this adequate for tool selection and invocation.

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

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

The input schema has 100% coverage with descriptions for sys_id and close_notes, so the schema carries the parameter semantics. The tool description adds no additional meaning about how these parameters should be used or formatted.

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 'Mark' with the resource 'task' and the action 'complete', clearly distinguishing it from generic tools like update_task or close_incident. The scope is unambiguous: it marks a task as complete. This is a precise and non-tautological purpose statement.

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

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

The description states the prerequisite WRITE_ENABLED=true, which gives some context for when the tool can be used. However, it does not explain when to use this tool versus alternatives such as update_task or close_incident, nor does it mention any exclusion scenarios. The context is implied 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 indicate a non-read-only, non-destructive, non-idempotent operation. The description adds only the purpose but does not disclose side effects such as locking the update set or irreversibility. It fails to provide meaningful behavioral context beyond the annotations.

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

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

The description is a single sentence plus a [Scripting] tag, conveying the essential action with no wasted words.

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

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

For a simple one-parameter state-change tool, the description is largely sufficient. However, it lacks context about the consequences of marking complete (e.g., whether the update set becomes locked) and how it relates to the many sibling update-set tools, leaving some ambiguity for an agent.

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

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

The schema fully describes sys_id as 'Update Set sys_id' with 100% coverage. The description adds no additional parameter information, 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 'Mark' with a clear object 'Update Set' and explains the intent 'ready for migration', distinguishing it from sibling tools like export_update_set or switch_update_set.

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 phrase 'ready for migration' implies the tool is used to prepare an update set for migration, but it does not explicitly state when to use it versus alternatives, nor does it mention any prerequisites or exclusions.

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

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

The description adds only the '[Write]' tag, which merely restates the readOnlyHint: false annotation. It provides no additional behavioral context such as required permissions, side effects, or impact on mobile clients. The annotations already convey the safety profile, so the description contributes almost nothing beyond them.

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

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

The description is a single sentence plus a tag, front-loaded and free of redundant text. Every word contributes to understanding the tool's 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?

Given the tool's simplicity (3 params, 1 required), full schema coverage, and annotations covering the safety profile, the description is largely sufficient for tool selection. The lack of usage guidance and behavioral details prevents a perfect score, but these are adequately compensated by structured metadata.

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

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

Schema description coverage is 100%, and each parameter (query, table, max_records) is already clearly described in the input schema. The tool description adds no parameter-specific details beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Configure' and identifies the resource 'which tables/records are available offline in mobile,' clearly distinguishing this from sibling mobile tools like create_mobile_app_config or list_mobile_app_configs.

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 is given on when to use this tool versus alternatives. Usage is implied by the purpose and name, but no exclusions or alternative tools are mentioned, leaving the agent to infer the appropriate context.

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

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

The description adds little beyond the annotations. The '[Write]' tag merely echoes readOnlyHint=false. It does not disclose side effects, overwrite behavior, permission requirements, or failure semantics. Since annotations already cover the safety profile, the description should add context but does not.

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

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

The description is a single, concise sentence that front-loads the action. No filler or redundant text beyond the '[Write]' tag, which is acceptable. It is appropriately sized for the tool.

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

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

Despite having 5 parameters and no output schema, the description is minimal. It does not mention expected outcomes, error conditions, or how parameters like 'query' and 'columns' affect the list view. The schema covers parameter names, but the description leaves contextual 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%, so all five parameters are described in the input schema. The description itself does not add any parameter-level meaning beyond what the schema 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 clearly states a specific action ('Add or update') on a specific resource ('list view in an agent workspace'), which distinguishes it from sibling tools like create_workspace or get_workspace. The verb and resource 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?

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where another tool (e.g., create_workspace) would be appropriate. The description only states what it does, not when 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?

The description contradicts the readOnlyHint=true annotation. It describes a copy operation that creates a new attachment on a target record and explicitly requires WRITE_ENABLED=true, which is a write operation. This is a serious inconsistency that could mislead an agent into thinking the tool has no 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 two sentences, front-loaded with the core action and key constraints (server-side, WRITE_ENABLED=true, bytes not passed). It conveys purpose and a use case with zero fluff, making it efficient and well-structured.

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

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

The description covers the essential context: what it does, the write requirement, and the typical use case. It does not mention error conditions or return values, but for a simple copy operation without an output schema, this is acceptable. However, the annotation contradiction undermines trust in the overall completeness.

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

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

The schema covers 100% of the parameters with descriptions. The tool description adds only a minor note about file_name defaulting to the source name, which is already in the schema. It does not add meaningful semantics beyond what the schema provides, 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 clearly states the action (copy an existing attachment), the source (existing attachment), and the target (another record). It also distinguishes itself from sibling tools like upload_attachment and read_attachment by noting the server-side execution and that file bytes never pass through, plus a concrete use case ('attach the same document from this record onto that KB / 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?

It provides a clear use case and explicitly mentions the WRITE_ENABLED=true requirement, which tells the agent when it can be used. It does not explicitly name alternatives, but the context of 'copy' vs 'upload' implies the distinction. This is adequate but could be stronger with explicit when-not-to-use guidance.

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

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

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), non-idempotent, non-destructive, and open-world. The description adds the NOW_ASSIST_ENABLED and WRITE_ENABLED requirements, which are useful environmental constraints not in annotations. However, it does not disclose side effects of creation (e.g., whether the workflow is immediately active, or if any related resources are changed) beyond the basic creation itself.

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 front-loads the primary action ('Create an agentic workflow linked to an AI agent') and appends the requirement in parentheses. It is concise, clear, and contains 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?

There is no output schema, so the description should explain what the response contains (e.g., the created workflow's sys_id), but it does not. The tool creates a potentially complex structure (steps array) without explaining how the workflow will be used or what happens after creation. The description is too sparse for a creation tool with these parameters and no schema-defined return.

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

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

Schema description coverage is 100% for all 5 parameters, so the baseline is 3. The description adds no additional meaning about parameter relationships (e.g., how steps relate to the agent, or that agent_sys_id must reference an existing agent). The schema descriptions are minimal, but coverage is complete, so a baseline score 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 a specific resource ('agentic workflow linked to an AI agent'), clearly stating what the tool does. It distinguishes this from sibling tools like 'create_ai_agent' (creates the agent itself) and 'create_flow' (regular flow) by specifying the workflow is agentic and linked to an AI agent.

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 prerequisites: 'requires NOW_ASSIST_ENABLED + WRITE_ENABLED', which provides clear conditions for when to use the tool. It also implies the need for an existing AI agent (since the workflow is 'linked to an AI agent'), but it does not mention alternatives like 'create_flow' for non-agentic workflows. Thus it gives clear context but lacks explicit exclusions or alternative tool references.

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

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

Beyond the annotations (readOnlyHint false, openWorldHint true), the description adds value by disclosing hard prerequisites (feature flags must be enabled) and a side effect (auto-generated ACLs). It does not contradict any annotation.

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

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

The description is a single sentence that front-loads the primary action and includes only high-value context: prerequisites and optional behavior. No filler or repetition.

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

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

For a straightforward create tool with a fully described schema and annotations, the description is sufficiently complete: it states purpose, prerequisites, and a key side effect. The lack of an output schema is not a major gap since create tools conventionally return the created object, though mentioning that explicitly would strengthen it.

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

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

Schema description coverage is 100%, so the schema already explains all four parameters. The description's mention of 'optional auto-generated ACLs' basically restates the auto_generate_acls property description without adding new parameter-level detail.

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

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

The description uses a specific verb and resource: 'Create an AI agent definition', which clearly distinguishes this tool from sibling tools like get_ai_agent, list_ai_agents, and create_agentic_workflow. The mention of 'optional auto-generated ACLs' adds precision about what the creation involves.

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 operational context by stating the required flags (NOW_ASSIST_ENABLED + WRITE_ENABLED) and the optional ACL generation behavior. However, it does not explicitly name alternatives or state when not to use this tool compared to similar creation tools like create_agentic_workflow.

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 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the write, non-idempotent, non-destructive nature is pre-disclosed. The description adds the requirement that SCRIPTING_ENABLED must be true, which is a useful behavioral constraint, and notes ES2021 support for scripts. Yet it does not disclose other behaviors like update set context or potential side effects beyond what openWorldHint already suggests.

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

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

The description is compact and front-loaded, with the core action in the first sentence. The second sentence about ES2021 support is a minor detail that does not bloat the description, keeping it appropriately 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?

Given the tool's complexity (7 params, 4 required, no output schema) and good annotations, the description covers the essential action and a key prerequisite. However, it does not mention what the tool returns after creation, nor how it interacts with update sets or other environment settings. This leaves some gaps for a mutation tool.

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

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

The input schema provides 100% coverage with descriptions for all 7 parameters, so the baseline is 3. The description's mention of ES2021 support is already present in the script parameter's schema description, so it does not add new meaning to the parameters. It adds no additional information about parameter formats or constraints.

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

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

The description opens with 'Create a new business rule', a specific verb+resource that clearly distinguishes it from siblings like update_business_rule, list_business_rules, and get_business_rule. The added prerequisite about SCRIPTING_ENABLED=true provides clarity about the operation's context.

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

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

The description implies the tool is for creating new business rules and explicitly notes a prerequisite (SCRIPTING_ENABLED=true). It also provides guidance on script syntax (ES2021 async/await). However, it does not mention alternatives or exclusions, such as using update_business_rule for modifications.

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), non-idempotent, and non-destructive. The description adds the WRITE_ENABLED prerequisite, which is useful context beyond annotations. However, it does not disclose creation behavior, potential side effects, or response format, though annotations partially cover the safety profile.

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

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

The description is a single sentence and highly concise, but it omits valuable detail that could be included without bloating. It is not overly verbose, but it is under-informative for a creation tool.

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

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

With four parameters including a nested 'fields' object, no output schema, and only basic annotations, the description leaves out key details such as what the fields object accepts, any required field validation, or what the created record looks like. An agent would need to infer too much to use it correctly.

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

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

Schema description coverage is 100%, so all parameters (name, fields, owned_by, support_group) are already documented. The description adds no extra meaning beyond what the schema provides, so a baseline 3 is appropriate.

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

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

States a specific verb and resource ('Create a business service (cmdb_ci_service)'), making the action clear. It does not differentiate from sibling creation tools like create_service_offering or create_csm_case, but the core 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 mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives, nor any context about typical scenarios or exclusions. An agent would have to infer usage from the name alone.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds the WRITE_ENABLED=true requirement, which is useful. However, it does not disclose what happens on success (e.g., return of sys_id) or any failure modes, and openWorldHint=true is not explained. It provides some behavioral context beyond annotations but not richly.

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 redundant information. It front-loads the core action and adds the crucial prerequisite. Every word 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 create operation with 5 parameters (1 required) and no output schema, the description is adequate but not complete. It does not mention the return value (likely sys_id), nor does it clarify openWorldHint implications or provide examples. Given the tool's simplicity, it meets a minimum viable level but leaves room for improvement.

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

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

Schema description coverage is 100%, so each parameter is described (e.g., title, fields, parent, catalog, description). The description does not add any additional meaning beyond the schema; it only reiterates the table name. Baseline of 3 is appropriate since the schema carries the parameter documentation.

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

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

The description clearly states the action (create), the resource (catalog category), and the specific table (sc_category). This distinguishes it from siblings like create_catalog_item and list_catalog_categories. It also notes the WRITE_ENABLED requirement, adding specificity.

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 it is for creating catalog categories but does not explicitly contrast with alternatives such as list_catalog_categories or create_catalog_item. The WRITE_ENABLED=true condition is a prerequisite, not a usage guideline for choosing this tool over others. Thus, guidance 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?

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?

The description adds the WRITE_ENABLED=true requirement, which is a behavioral prerequisite beyond the annotations. However, it doesn't disclose other behavioral traits such as what happens on success, whether an approval is triggered, or what the return value is.

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 quickly states the action and a key prerequisite, with no filler 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?

Given the tool has 15 parameters and no output schema, the description is too minimal. It doesn't explain what the tool returns, how the 'type' field affects behavior, or any post-creation steps. The WRITE_ENABLED hint is useful but insufficient for a complex creation 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?

All 15 parameters are described in the input schema with 100% coverage. The description adds no additional parameter-level meaning beyond the schema, so the baseline score 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 'Create' with a clear resource 'change request', making the tool's purpose immediately obvious and distinct from sibling tools like update_change_request or list_change_requests.

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

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

The description provides a prerequisite (WRITE_ENABLED=true) but does not explicitly mention when to use this tool instead of alternatives like update_change_request. The usage is implied by the verb 'Create', but there is no explicit exclusion or comparison.

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's '[Write]' prefix aligns with readOnlyHint=false but adds no behavioral details beyond what annotations already convey—such as failure modes, uniqueness constraints, or side effects. It neither enriches nor contradicts 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?

A single, front-loaded sentence with no filler. Compact and to the point.

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?

While simple, the description omits details like whether existing relationships are checked, required permissions, or the return value. For a 3-parameter create tool with no output schema, it is minimally adequate but not fully 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 covers all three parameters (type, child, parent) with descriptions, so the description adds no additional parameter semantics. Baseline 3 applies due to 100% schema coverage.

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

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

The description uses the specific verb 'Create' and identifies the resource as 'a relationship between two CMDB Configuration Items,' clearly distinguishing it from read-only sibling tools like list_relationships and get_cmdb_ci.

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, such as checking existing relationships with list_relationships first. Usage is only implied by the verb 'Create.'

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 indicate a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the WRITE_ENABLED=true requirement, which is useful context, but does not disclose side effects, return behavior, or failure modes.

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

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

The description is a single, front-loaded sentence with no filler; it states the operation and the key precondition clearly and 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?

The schema and annotations cover parameters and safety, but the description lacks any mention of the return value or success behavior. With 9 parameters and no output schema, some additional context would help, but it is minimally 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?

All 9 parameters have schema descriptions (100% coverage), and the tool description adds no additional parameter-level meaning, so baseline 3 applies.

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

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

The description uses the specific verb 'Create' and resource 'Customer Service case', which clearly distinguishes it from sibling tools like update_csm_case, close_csm_case, and other create_* tools for different domains. 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 only mentions a precondition (WRITE_ENABLED=true) but does not explain when to choose this over alternatives like create_incident or create_hr_case, nor does it provide exclusions or alternatives. There is no guidance on tool 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 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 declare readOnlyHint=false (write operation) and destructiveHint=false, so the write nature is already known. The description adds the WRITE_ENABLED requirement and the fact that it's an 'add' operation, which is useful. However, it does not disclose whether the operation appends or overwrites existing inputs, nor any response behavior. 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 states the action, the target resource, and a critical requirement. No unnecessary words or fluff. It is front-loaded with the core information, making it easy for an agent to parse quickly.

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 is a simple CRUD operation with a fully described schema and the description names the target table, the essential information is present. The lack of an output schema is not critical for a create operation, and the agent can infer the purpose from the name and schema. However, it could mention that this is for adding an input to an existing decision table, which is implied but not explicit.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters (name, type, order, fields, decision_sys_id). The description does not add any additional parameter meaning beyond what is already provided. It only mentions the target table, which is already captured in the decision_sys_id parameter. Thus, it adds no value beyond the baseline for fully covered schemas.

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

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

The description clearly states the action ('Add an input to a decision table') and specifies the exact table (sys_decision_input). It distinguishes itself from siblings like create_decision_table (which creates the table itself) and list_decision_inputs (which lists existing inputs). The verb-resource pairing 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 includes the prerequisite 'Requires WRITE_ENABLED=true', which is a useful condition, but it does not explain when to use this tool versus alternatives such as create_decision_table or update operations. The usage context is implied (add input to an existing decision table) but not explicitly stated, and no alternatives are named.

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 idempotent. The description adds the WRITE_ENABLED=true requirement, which is useful but does not disclose other behaviors such as whether creation triggers any validation, side effects, or requires subsequent publishing. The added value over annotations is minimal.

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