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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single, front-loaded sentence that states the action and a key prerequisite. No redundant filler or restatement of the tool name. It earns its place.

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

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

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

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

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

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

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

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

The description clearly states the action ('Add'), the specific resource ('internal work note'), and the scope ('any ITSM record'). The word 'internal' distinguishes it from sibling tool 'add_comment', which presumably adds a visible comment, so the purpose is unambiguous.

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

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

The description does not provide guidance on when to use this tool versus alternatives like 'add_comment' or 'update_record'. It mentions a prerequisite ('requires WRITE_ENABLED=true'), but this is a constraint rather than usage direction. No exclusions or alternative tool references are given.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints, so the bar is lower. The description adds context about the semantic AI-powered nature, which is a behavioral trait beyond annotations.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With no output schema, the description should explain what the tool returns (e.g., success status, updated record) and any side effects (e.g., workflow triggers). It does not. For an approval tool with moderate complexity, this is a significant gap.

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

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

Schema covers 100% of parameters with descriptions. The description does not add additional semantic information about the parameters beyond what the schema provides. Baseline score of 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already indicate destructiveHint=true. The description adds the requirement for WRITE_ENABLED and specifies that the request must be 'open', providing useful behavioral context beyond annotations.

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

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

Single sentence with no unnecessary words. Straightforward and efficient.

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

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

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

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

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

Schema descriptions already cover both parameters with adequate detail. The description does not add significant extra meaning beyond the schema context of 'open service catalog request'.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, with clear descriptions for each parameter (table, sys_id, new_name, target_scope). The description's 'new name/scope' phrasing maps to the new_name and target_scope parameters, but adds no extra detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Clone') and resource ('platform artifact') with explicit outcome ('to a new name/scope'). It clearly distinguishes itself from sibling artifact tools like push_artifact, pull_artifact, and sync_status by focusing on duplication rather than transfer or synchronization.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single front-loaded sentence: 'Close an HR case with resolution notes (requires WRITE_ENABLED=true).' It conveys the verb, resource, input, and a critical prerequisite with no filler or redundancy.

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

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

For a 3-parameter tool with rich annotations (destructiveHint, readOnlyHint, idempotency, openWorld) and full schema coverage, the description and annotations together provide a solid operational picture. The WRITE_ENABLED prerequisite is a valuable addition. The only omission is return value/confirmation behavior, which is minor given the simple close action and lack of an output schema.

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

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

Schema description coverage is 100%, with all three parameters (sys_id, close_code, close_notes) already documented. The description's 'with resolution notes' merely reiterates the close_notes parameter without adding format, examples, or constraints. Baseline 3 applies.

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

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

The description uses the specific verb 'Close' with the explicit resource 'HR case', clearly distinguishing it from sibling tools like close_incident, close_change_request, and update_hr_case. The 'with resolution notes' phrase adds meaningful specificity about the tool's primary function, making it unambiguous.

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

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

The description implies the tool is for closing HR cases with resolution notes, but provides no explicit guidance on when not to use it or which alternatives apply (e.g., update_hr_case for non-closing modifications, close_csm_case for CSM cases). An agent relies primarily on the tool name and sibling context rather than explicit direction.

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

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

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

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

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

The description is a single, front-loaded sentence that immediately states the verb and object, with a useful parenthetical for the permission requirement. No wasted words; every part contributes to understanding the tool's purpose and precondition.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true) suggest possible side effects, but the description fails to elaborate on behavioral traits such as whether analysis creates records or has performance implications, leaving ambiguity.

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

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

The description is a single efficient sentence that quickly conveys the tool's purpose, although it could be slightly more structured.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The schema covers 100% of parameters with a clear description for 'sys_id'. The tool description adds no extra semantic value beyond what the schema already provides.

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

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

The description clearly states a specific verb ('Commit') and resource ('update set'), distinct from sibling tools like 'publish_changeset' or 'complete_update_set'. It also adds a prerequisite condition.

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

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

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

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

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

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

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

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

The description is a single sentence front-loaded with the verb and resource. It is concise with no wasted words, though the mention of 'time periods' could be removed or aligned with actual parameters.

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

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

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

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

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

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

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

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

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

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

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

The description notes it is 'useful for capacity planning', providing a usage context. However, it does not explicitly state when to use this tool versus alternatives like 'get_table_record_count' or 'trend_query', nor does it offer exclusions or prerequisites.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single concise sentence with a minimal tag. It is efficient and front-loaded, though it sacrifices completeness for brevity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single sentence that is direct and front-loaded with the action and resource. It avoids unnecessary detail and earns its place.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single, front-loaded sentence that states the verb and scope without any fluff. It is exactly as concise as it needs to be.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single, front-loaded sentence with a '[Write]' prefix that immediately signals the operation type. It is concise, with no wasted words or redundant information.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is a single sentence that includes the essential purpose and a key prerequisite. It is concise with no unnecessary words, and the information is front-loaded. Every part earns its place, making it highly efficient for an agent to parse.

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

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

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

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

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

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

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

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

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

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

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

The description only mentions a prerequisite (WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives, such as update_change_request or submit_change_for_approval. There is no indication of exclusions or recommendations. This leaves the agent without context for appropriate usage, resulting in a low score.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, meaning all 9 parameters have descriptions in the schema. The tool description does not add any additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description reveals that the created change request will be 'linked to a DevOps deployment,' which is a behavioral detail beyond the annotations. Annotations (readOnlyHint: false, idempotentHint: false, destructiveHint: false) already indicate a non-read, non-idempotent, non-destructive write operation, and the [Write] marker is consistent but redundant. The linking behavior is useful additional 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, front-loaded sentence with no filler. The [Write] marker is redundant given the annotations, but the overall length is appropriate and 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 create tool with 7 parameters, all documented in the schema, and with annotations covering safety, the description covers purpose and the linking behavior. There is no output schema, but that is typical for create operations. It is sufficient for an agent to understand when and how to use the tool, though it could briefly mention required parameters.

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

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

The input schema provides descriptions for all 7 parameters (100% coverage), so the baseline is 3. The description does not add parameter-specific details, though the phrase 'linked to a DevOps deployment' loosely implies that parameters like pipeline/artifact are relevant to establishing that link.

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' with a clear resource: 'a change request linked to a DevOps deployment for change governance.' This distinguishes it from the sibling tool create_change_request, which is a general change request tool, by specifying the DevOps linkage and governance 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 implies usage for creating change requests connected to DevOps deployments but does not explicitly state when to use it instead of alternatives like create_change_request, nor does it mention when not to use it. It lacks explicit exclusions or alternative 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?

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds the WRITE_ENABLED=true requirement, which is useful context not captured by annotations. However, it does not disclose other behavioral traits like return value or side effects, so credit is partial.

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 front-loaded and contains no filler. It is appropriately concise 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?

The tool is simple with full schema coverage and annotations. However, it lacks usage guidance and does not explain the return value (no output schema exists). Still, for a straightforward create operation, the provided information 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%, so all three parameters are already documented. The tool description adds no parameter semantics 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 'Create a new epic' uses a specific verb and resource, clearly distinguishing it from siblings like update_epic and list_epics. The purpose is unambiguous and immediately 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 provides no guidance on when to use this tool versus alternatives such as update_epic or create_story. The only extra information is the WRITE_ENABLED=true prerequisite, which is not usage guidance.

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

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

The description adds no behavioral context beyond what annotations already provide. It repeats the write nature ('[Write]') which is already indicated by readOnlyHint: false, and fails to mention important traits such as the flow being created in draft state (since publish_flow exists) or any permissions needed. With annotations covering the safety profile, the description contributes no extra transparency.

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

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

The description is a single short sentence and is very concise, with no wasteful language. However, the '[Write]' tag is redundant given the annotation readOnlyHint: false, slightly reducing the efficiency of the text.

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

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

No output schema is provided and the description does not mention return values or post-creation state (e.g., whether the flow is active or draft). Given the sibling tool publish_flow, the description should clarify that create_flow likely creates an inactive flow, but it does not. This is a significant lack of context for a mutation tool with no output schema.

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

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

Schema description coverage is 100% for all 5 parameters, so the schema fully documents each parameter. The description adds no additional semantic meaning for the parameters (e.g., how they interact or required fields beyond 'name'), so it does not compensate or enrich beyond the schema.

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

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

The description clearly states the action (create) and the resource (Flow Designer flow), with a specific verb+resource combination. It distinguishes itself from sibling tools like update_flow, list_flows, and get_flow by explicitly targeting the creation of a new flow.

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 when the goal is to create a new flow, but provides no explicit guidance on when to use this vs. alternatives like create_subflow or create_flow_action. No exclusions or alternative recommendations are given, so the context 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?

Annotations already indicate readOnlyHint=false, so the write nature is known. The description adds a '[Scripting]' tag, which gives a hint about the target audience, but does not disclose additional behavioral traits such as permissions, validation, or side effects. No contradiction exists.

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: a single sentence plus a tag. It is front-loaded and wastes no words, fitting the standard for efficient descriptions.

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 the schema covers parameters and annotations provide safety hints, the description lacks information about return values, prerequisites, or any special context needed for scripting. For a creation tool with multiple parameters, this is adequate but leaves some gaps.

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

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

The description does not add any meaning beyond the input schema, which already documents all five parameters with descriptions. Since schema description coverage is 100%, the baseline of 3 is appropriate; no extra value is provided.

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

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

The description clearly states the tool creates a custom Flow Designer action, using a specific verb and resource. It distinguishes from the sibling create_flow and other create tools by explicitly naming the artifact type (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?

No usage guidance is provided. The description does not explain when to use this tool versus alternatives like create_flow or create_subflow, nor any prerequisites or context for creating an action.

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, destructiveHint:false), the description adds only '[Write]', which is redundant. It does not disclose non-idempotency, validation rules, or what the response contains. No additional behavioral context is offered.

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

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

The description is a single, short sentence plus a minimal '[Write]' marker. It is front-loaded with the primary purpose and contains zero unnecessary words.

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

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

For a simple create operation with full schema coverage and annotations, the description is minimally adequate. However, it does not mention that each call creates a distinct record, possible return values, or any prerequisites beyond the schema, leaving a moderate gap.

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

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

The input schema describes all 6 parameters with full coverage (100%), including names and descriptions. The tool description contributes nothing about parameters, 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 'Create a new GRC risk entry' uses a specific verb and resource, clearly distinguishing it from sibling tools like list_grc_risks and get_grc_risk. There is no ambiguity about what operation this performs.

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 explicitly name alternatives or exclusions, but the create verb and the sibling set (list/get only) make it clear this is the tool for adding a new risk. Context is clear, though no direct comparison is provided.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation is expected. The description adds the critical behavioral requirement of WRITE_ENABLED=true, which is not in the annotations. This is useful context that goes beyond structured data, though it does not describe side effects or response behavior.

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

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

The description is a single, focused sentence that conveys the purpose and a key prerequisite. No wasted words; it is appropriately sized for a simple create operation.

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, schema covers all parameters, and no output schema exists. The description provides the essential purpose and the WRITE_ENABLED constraint. It could have elaborated on expected return values, but for a straightforward create operation, the information 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?

Schema description coverage is 100% with clear descriptions for all three parameters (name, manager, description). The description adds no additional parameter meaning beyond what is already in the schema, 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 'Create' with a clear resource 'assignment group', distinguishing it from related group management tools like update_group or add_user_to_group. It also adds a useful operational condition (WRITE_ENABLED=true) that clarifies the intended use.

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 usage is implied by the verb 'Create' and the tool name, but there is no explicit guidance on when to use this vs. alternatives such as update_group for existing groups. The WRITE_ENABLED requirement is a prerequisite, not a usage guideline. No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already indicate it's a write operation (readOnlyHint=false). Description adds the WRITE_ENABLED requirement, which is useful. However, it doesn't disclose side effects like triggering workflows or notifications.

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

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

Single sentence, no unnecessary words. The requirement is front-loaded. Excellent conciseness.

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

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

No output schema and no mention of return values or success/error responses. With 6 parameters and many similar sibling tools, the description should provide more context (e.g., what the response includes, example usage).

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 6 parameters have descriptions in the input schema, so schema coverage is 100%. The description adds no additional meaning beyond what's already provided in the schema.

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

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

The description clearly states the action 'Create' and the resource 'HR Service Delivery case'. It distinguishes from sibling tools like update_hr_case or close_hr_case. The additional requirement note does not detract.

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 on when to use this tool versus alternatives like create_hr_task or other creation tools. The WRITE_ENABLED requirement is a precondition, not usage context.

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

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

The description aligns with annotations (readOnlyHint=false) and adds a permission requirement (WRITE_ENABLED=true), but does not elaborate on side effects, return values, or other behavioral traits. Since annotations already indicate a write operation, the added value is moderate.

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

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

The description is a single, efficient sentence that conveys the action and a key prerequisite with no filler or redundant information. It is front-loaded with the verb and resource.

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 fully described parameters and safety annotations, the description is adequate. It could mention that the task is created as a child record of the HR case, but this is implied by 'within an HR case.' The absence of an output schema reduces the need for return-value details.

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 4 parameters, so the description does not need to add parameter details. It provides the baseline level of clarity without adding extra meaning.

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

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

The description clearly states the action ('Create') and the resource ('a task within an HR case'), which is specific and distinguishes it from sibling tools like create_hr_case (creates a case) and list_hr_tasks (lists tasks). The scope is precise 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 provides a clear context (creating tasks inside HR cases) and a prerequisite (WRITE_ENABLED=true), which implies when it can be used. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of full 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 readOnlyHint=false and destructiveHint=false. The description adds the WRITE_ENABLED=true requirement and clarifies the row is staged for later transformation, which is useful. However, it does not disclose return values, error behavior, or validation details, so it provides only moderate additional transparency.

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 redundant wording. It states the core action, the target, the purpose, and a necessary requirement in one concise line.

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 purpose and a prerequisite. However, it does not mention what the tool returns (e.g., the created row's sys_id), which is notable since there is no output schema. Error behavior and how the data parameter maps to columns are also not addressed, leaving some gaps for a simple tool.

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

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

Schema coverage is 100%, with both parameters described adequately (staging_table has an example and a constraint; data is described as 'Key-value pairs'). The description adds no extra parameter semantics, but since the schema carries the burden, 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 ('Insert'), the target ('an Import Set staging table'), and the purpose ('for later transformation'), distinguishing it from generic record creation tools like create_record. It is specific and unambiguous.

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

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

The description provides clear context: the row is inserted for later transformation, implying it is a preparatory step before running a transform map. It also states a required prerequisite (WRITE_ENABLED=true). It does not explicitly mention alternatives or when not to use it, but the context is sufficient.

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. The description adds the prerequisite condition (WRITE_ENABLED=true), which is valuable context beyond annotations. However, it does not disclose what the tool returns (e.g., created record sys_id) or mention side effects like notifications, leaving behavioral transparency adequate but not excellent.

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 a parenthetical condition, containing zero unnecessary words. It is well front-loaded with the verb and resource, making it exceptionally concise and easy to parse.

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

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

For a tool with 9 parameters and no output schema, the description is minimal. It covers the core purpose and a key prerequisite, but does not explain return values or typical usage flow. Given the complexity, a bit more context (e.g., 'Returns the sys_id of the created incident') would improve completeness, but it is not severely lacking.

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 9 parameters with descriptions, achieving 100% coverage. The description does not add any parameter-specific details beyond the schema, so it does not compensate further. Baseline 3 is appropriate given schema richness.

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

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

The description clearly states the verb 'Create' and the resource 'incident record', making the purpose unmistakable. It also mentions the prerequisite condition ('requires WRITE_ENABLED=true'), which further clarifies the tool's use. Given the sibling tools (update_incident, close_incident, etc.), it effectively distinguishes itself.

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 one key prerequisite ('WRITE_ENABLED=true'), which is helpful but does not offer broader guidance on when to use this tool versus alternatives like update_incident or resolve_incident. No comparison to siblings or exclusions are provided, so the agent must infer context from the tool 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?

The description adds the 'requires WRITE_ENABLED=true' requirement, which is not present in annotations. However, it does not disclose other behavioral traits such as return values, error conditions, or side effects. Annotations already cover readOnly and destructive hints, so the additional context is limited but nonzero.

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 core action and a key prerequisite efficiently, making every word valuable.

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 too sparse for a create operation. It does not mention what the response contains (e.g., sys_id of the created article) or any potential side effects. Since there is no output schema, the description carries the burden of explaining return behavior, which it fails to do. The schema covers parameters, but the overall context remains 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 already provides descriptions for all 4 parameters (100% coverage), so the description does not need to add parameter details. It adds no additional meaning beyond what the schema provides, yielding the baseline score of 3.

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

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

The description clearly states the action ('Create a new knowledge article') and the resource. It does not explicitly differentiate from sibling tools like update_knowledge_article or publish_knowledge_article, but the verb 'create' is unambiguous and distinct enough.

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 on when to use this tool versus alternatives. The parenthetical 'requires WRITE_ENABLED=true' is a precondition, not a usage scenario, and there is no mention of using update for existing articles or publish for lifecycle transitions.

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

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

The annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write operation. The description's '[Write]' tag merely duplicates that annotation without adding further behavioral context such as side effects, required permissions, or what happens to existing data. It adds no new information beyond 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, front-loaded sentence with no wasted words. The '[Write]' tag is arguably redundant, but the structure is efficient. It could have packed more useful information in the same space, so it doesn't earn a 5.

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

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

For a mutation tool with six parameters and no output schema, this description is woefully incomplete. It does not explain what the tool returns (e.g., the created KPI object or an ID), any special behavior, or how it fits with sibling tools like create_pa_indicator. Given the tool's complexity, the description provides insufficient context for an agent to invoke it correctly with confidence.

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

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

Input schema coverage is 100%, so all six parameters (name, unit, field, table, aggregate, conditions) have descriptions. The description does not elaborate on parameter semantics, but the schema already carries that burden, making a baseline score of 3 appropriate. No additional insight is provided in the description.

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

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

The description clearly states the action (Create) and resource (Key Performance Indicator), with an additional scoping phrase 'from ServiceNow data' that adds context beyond the tool name. However, it does not distinguish itself from sibling tool 'create_pa_indicator', which likely overlaps in purpose, so it misses the top score.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when to prefer create_kpi over create_pa_indicator, or any other contextual usage direction. The description leaves the agent to infer usage solely from the name.

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 no behavioral context beyond what annotations already indicate. The annotation readOnlyHint=false already signals a write operation, and the '[Write]' tag in the description merely reinforces that without adding details about side effects, uniqueness constraints, or what happens to existing configurations. It does not contradict annotations, but provides minimal extra 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, direct sentence plus a short marker. It is front-loaded with the key information (action and object) and contains no filler, making it highly concise and easy to parse.

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

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

This is a simple create operation with 3 parameters and no output schema. The description is minimal but not misleading. However, it lacks any context about what a mobile app configuration entails, how it relates to sibling tools like list_mobile_app_configs, or any constraints on the fields. This is acceptable for a basic tool 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?

The schema already documents 'name' and 'branding_color' with descriptions, covering 67% of parameters. The tool description does not add any parameter-specific information, so it relies on the schema. Since coverage is moderate and the description is silent, a baseline of 3 is appropriate—neither enhanced nor compensated.

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 a new mobile app configuration.' This uses a specific verb ('Create') and a specific resource ('mobile app configuration'), distinguishing it from sibling tools like list_mobile_app_configs and get_mobile_app_config, which have different purposes.

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

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

No guidance is provided on when to use this tool versus alternatives such as create_mobile_applet or create_mobile_layout. There is no mention of prerequisites, required permissions, or scenarios where this tool is preferred, 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.