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

The description discloses that the tool 'modifies the code search configuration on the instance' and includes a warning to verify table name and fields. This adds context beyond the annotations, which already indicate readOnlyHint=false and destructiveHint=false. The behavioral effect on future searches is also explained.

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, with three sentences: purpose, prerequisites, and warning. It is front-loaded and every sentence contributes operational value.

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

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

Given a simple 4-parameter tool with annotations and full schema coverage, the description covers the action, the prerequisite sys_id lookup, the effect on searches, and a safety warning. No output schema is needed, and the description adequately prepares the agent for invocation.

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

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

The schema covers 100% of parameters with detailed descriptions, including examples and references to lookup_table/lookup_columns. The tool description adds minimal param-specific detail beyond the schema, summarizing requirements but not enriching the semantics further.

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 a new table to an existing code search group') and its effect ('expanding what gets searched'). It distinguishes from sibling tools like list_code_search_groups and code_search by focusing on the modification 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?

It provides explicit prerequisites: 'Requires the search group's sys_id (get it from list_code_search_groups) and the table name and fields to search.' This tells the agent when to use it and what preparatory steps are needed. However, it doesn't explicitly contrast with alternatives for 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 mark the operation as mutating and non-idempotent. The description adds valuable behavioral context: comments are customer-visible by default, while work notes are internal to fulfiller staff. It does not contradict the annotations and goes beyond their basics.

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

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

The description is exactly two sentences: the first states the core function and scope, the second clarifies the key parameter behavior. It is concise, front-loaded, and contains no superfluous 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 with no output schema, the description covers the essential context: what the tool does, what record types it applies to, and how to switch visibility. It doesn't mention return values or error handling, but those are less critical for this kind of tool and the schema documentation fills in the parameter 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 descriptions cover 100% of parameters, so the baseline is 3. The description reinforces the is_work_note parameter's effect but adds no new details beyond what the schema already states (e.g., visibility semantics). No additional parameter-level insight 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 states a specific verb ('Add') and resource ('a comment or work note to any task-based record'), and explicitly names example record types. It clearly distinguishes the tool's function from sibling tools like assign_task or close_incident by focusing solely on adding comments/notes.

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 indicates the tool's purpose and the two modes (comment vs. work note), so an agent knows when to use it. However, it does not explicitly mention when not to use it or point to alternative tools for other record modifications, leaving the differentiation to inference.

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

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

Annotations already indicate readOnlyHint and openWorldHint, so the bar is lower. The description adds that it 'returns per-group statistics' and works on 'any' table, reinforcing but not substantially expanding beyond annotation-driven expectations. It omits details like default behavior if no aggregate functions are specified.

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 tight sentences plus a list of examples. It is front-loaded with the core behavior and every sentence earns its place with zero 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 complexity (11 parameters, no output schema), the description covers the core use case and examples. It lacks details on return format and edge cases (e.g., behavior when no aggregate function is selected), but annotations and rich schema descriptions fill many 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 all 11 parameters having descriptions. The description adds illustrative examples but does not explain parameters beyond the schema. The baseline of 3 is appropriate since the schema takes the primary burden.

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 ('Run aggregate functions'), the resource ('any ServiceNow table'), and the distinguishing grouping behavior ('grouped by a field'), which separates it from sibling tools like aggregate_query and count_records. The examples further illustrate its purpose.

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

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

The phrase 'ideal for breakdowns and dashboards' and concrete examples ('count of incidents grouped by priority') give clear context for when to use this tool. However, it does not explicitly contrast with alternative tools like aggregate_query or define when grouping is unnecessary.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds valuable transparency by stating that it uses the Stats API and returns computed statistics without individual records, which helps the agent anticipate the output. It does not discuss rate limits or authentication, but given annotations cover safety, this is acceptable.

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: the first defines the tool's function, the second provides illustrative examples. It is front-loaded, with no redundant phrases or filler content. Every sentence contributes to understanding the tool's purpose and usage.

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

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

Given the complexity of 9 parameters and no output schema, the description does not explain the exact structure of returned statistics. However, the schema thoroughly documents all inputs, and the description clarifies what the tool returns (computed statistics, not records). The examples provide real-world context. Slight gap in not describing output format, but overall adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so each parameter is already well-documented with its own description. The tool description does not add significant parameter-level detail beyond naming the aggregate functions, which maps directly to the array fields (avg_fields, max_fields, etc.). Since the schema carries the semantic load, 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 tool runs aggregate functions (COUNT, AVG, MIN, MAX, SUM) on ServiceNow tables using the Stats API. It explicitly notes that it returns statistics without individual records, which distinguishes it from query_table and count_records. The inclusion of concrete examples (average resolution time, max priority, etc.) further clarifies the 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 practical use cases through examples, indicating when the tool is appropriate. However, it does not explicitly mention alternatives or situations where a different sibling tool (e.g., aggregate_grouped or count_records) would be preferred. The phrase 'on any ServiceNow table' implies general applicability, but exclusions are absent.

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

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

The description discloses the specific mutation (sets approval field to 'approved') and emphasizes that it changes the approval status. This adds useful context beyond the annotations (readOnlyHint=false, idempotentHint=true) and does not contradict them. It could also mention idempotent behavior, but the annotation covers that.

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

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

Three short sentences with no filler. The action, object, and effect are front-loaded, and the 'IMPORTANT' warning adds emphasis without redundancy.

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

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

For a simple write operation with full schema documentation and no output schema, the description covers purpose, effect, and safety warning. It does not explain behavior for already-approved requests or error conditions, but the idempotent annotation and general simplicity make this adequate.

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

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

Schema coverage is 100%, so each parameter (sys_id, comments, instance) is already well-documented. The description adds no new meaning beyond reiterating 'optional comments', which is already in the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Approve'), identifies the resource ('change request'), and states the exact effect ('Sets the approval field to approved'). This clearly distinguishes it from sibling tools like close_incident or resolve_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?

The description implies the tool is used to approve change requests, and the context makes it the only tool for that purpose among siblings. It does not explicitly mention alternatives or when not to use, but no conflicting tool exists, so the guidance is adequate.

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 idempotentHint=true, but the description adds useful behavioral context by noting the assignment_group field is updated when provided. This clarifies the operational impact beyond the basic write operation.

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

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

The description is two sentences, front-loaded with the action and target, followed by the scope. Every word earns its place, with no redundant information or filler.

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

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

For a straightforward assignment operation with good annotations and full schema coverage, the description sufficiently covers purpose, scope, and a key behavioral detail. It does not explain return values, but no output schema exists and this is a simple write action, so completeness is adequate.

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

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

Schema description coverage is 100%, with each parameter already well-documented. The tool description adds limited new meaning—only the optionality of assignment_group—so it relies on the schema for parameter understanding, matching the baseline for high coverage.

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

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

The description uses a specific verb 'assign' with a clear resource 'task record' and optional 'assignment group'. It also defines the scope as 'any task-based table', which distinguishes it from sibling tools that target specific task types or actions (e.g., close_incident, add_task_comment).

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

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

The description states it works on any task-based table, clearly indicating broad applicability for assignment operations. However, it does not explicitly call out when not to use it or reference alternative tools, leaving some room for interpretation.

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 meaningful behavioral context beyond annotations: operations are sequential, variable references are supported via saveAs/${key}, and there is an explicit warning that records are created on the instance. Annotations already indicate this is a write operation (readOnlyHint=false), so the description complements rather than repeats.

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

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

The description is well-structured, starting with the core function, then explaining variable references, followed by an illustrative example and a brief warning. It is somewhat verbose but each section earns its place by clarifying key usage patterns.

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 multi-step operations and variable references, the description covers the essential behavior, including sequential execution, saveAs mechanics, and a warning. It does not discuss transaction behavior or return values, but the schema covers the transaction parameter and there is no output schema, so the description is adequately complete.

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

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

Schema coverage is 100%, but the description enriches parameter understanding by explaining how saveAs and ${name} references work together with a concrete example. This is beyond the schema's basic field descriptions, providing practical semantics for the operations array.

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

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

The description clearly states the tool's function: 'Create multiple records across one or more ServiceNow tables in a single batch.' It uses a specific verb ('Create') and resource ('records across ServiceNow tables'), and the batch context distinguishes it from single-record creation and other batch tools like batch_update_records.

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

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

The description explains the tool's capability and provides an example of sequential dependency, but it does not explicitly state when to prefer this over alternatives like batch_update_records or query_update_records. The use case is implied but not directly contrasted with siblings, so it meets the minimum for clear context without exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'IMPORTANT: This modifies records' is consistent but largely redundant. It does not add deeper behavioral context such as partial failure semantics or permissions, but there is no contradiction.

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

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

The description is three short sentences, each serving a clear purpose: stating the operation, outlining the update structure, and reinforcing the mutating nature. No filler or unnecessary detail.

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

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

Given the rich annotations and 100% schema coverage, the description is complete enough for a batch update tool. It clearly states the action and the data shape, though it could briefly note non-atomic behavior; the stop_on_error parameter in the schema partially covers that gap.

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

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

Schema coverage is 100%, and the description only restates the core per-item fields (table, sys_id, field data). It does not add meaning beyond what the input 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 starts with a specific verb 'Update' and a clear resource: 'multiple records across one or more ServiceNow tables in a single batch.' This makes the tool's purpose immediately evident and distinguishes it from create or query-based update tools.

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

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

The description clearly communicates when to use this tool: when updating multiple records across one or more tables in a single batch. It does not explicitly name alternatives like query_update_records, but the context is unambiguous and sufficiently scoped.

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 mark destructiveHint=true and readOnlyHint=false, but the description adds irreversibility by stating 'the flow will be permanently cancelled and cannot be resumed'. This goes beyond the annotations and provides critical behavioral context. No contradiction exists between description and annotations.

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

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

The description is compact: two sentences plus a bolded important warning. It is front-loaded with the action, followed by usage guidance, then the critical destructive caveat. Every sentence serves a purpose with no fluff.

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

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

For a destructive tool with three parameters and no output schema, the description covers the what, when, and the irreversible consequence. It does not describe return values, but the tool is simple and annotations already convey the safety profile, so the overall context 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%, so all three parameters (reason, instance, context_id) are fully documented in the schema. The description reinforces the role of context_id but adds no additional parameter-level meaning beyond what the schema already provides, which fits the baseline.

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

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

The description opens with a specific verb-resource pair, 'Cancel a running or paused flow execution by its context ID', which clearly states what the tool does. This distinguishes it from sibling flow tools like execute_flow and get_flow_context_status by focusing on the cancellation action and the method (context ID).

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

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

It explicitly lists use cases ('no longer needed, is stuck in a waiting state, or was started by mistake'), giving an agent clear contexts for invoking the tool. It does not mention alternatives or when NOT to use it, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint true, so the read-only nature is covered. The description adds valuable behavioral context: sections can be individually enabled/disabled, and it mentions the returned sections. This goes beyond the annotations and helps the agent understand the tool's flexibility.

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

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

The description is two sentences, front-loaded with the core purpose, and the second sentence adds a key capability (enable/disable sections) without redundancy. It is concise and well-structured.

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

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

Given 7 parameters, no output schema, and readOnly annotations, the description covers the tool's overall behavior, return content, and configurability. It does not detail output formatting or error cases, but for a health check tool with this level of annotation support, it is 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?

Schema description coverage is 100%, so the parameters are fully documented in the schema. The description gives a high-level overview but does not add parameter-level meaning 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 'Run' and clearly identifies the resource ('consolidated health check on a ServiceNow instance') and the outputs (version info, cluster node status, stuck scheduled jobs, active semaphore count, operational counts). This distinguishes it from sibling tools like query_table or aggregate_query.

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

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

The description provides an explicit use case: 'Use this to quickly assess the overall health and status of an instance.' It does not name alternatives or exclusions, but the context is clear enough that an agent would know when to choose this tool over more specific query tools.

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

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

Annotations already indicate non-read-only, non-idempotent, and non-destructive. The description adds useful context by explicitly noting the tool creates a new update set, copies all records, and starts in 'in progress' state. However, the phrase 'all records on the instance' is ambiguous (could be misread as instance-wide rather than from the source update set), and there is no mention of permissions 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 brief and front-loaded, with the core action stated in the first sentence. The IMPORTANT note adds emphasis on the side effect but is not excessively verbose. Every sentence contributes to understanding the tool's behavior.

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 three fully described parameters and no output schema, the description covers the action, the resulting state, and the side effect. It lacks information about return values and potential failure conditions, but given the low complexity and existing annotations, it is reasonably complete. The ambiguity in 'all records on the instance' slightly detracts.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description only indirectly references new_name ('specified name') and source_sys_id ('existing update set') without adding meaningful details beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool clones an existing update set by creating a new one and copying all its records, specifying the resulting state ('in progress'). The verb 'clone' and resource 'update set' are specific, and the behavior is distinct from sibling tools like create_update_set or move_update_set_records.

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

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

The description implies the use case (duplicating an update set) but does not explicitly state when to use this vs alternatives like create_update_set or move_update_set_records. No exclusions or alternative comparisons are provided, leaving the agent to infer usage from the term 'clone'.

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 behavioral context beyond the annotations by explicitly stating 'This changes the incident state' and specifying the exact state value. It also notes the prerequisite about Resolved state. The annotations (readOnlyHint=false, idempotentHint=true) are consistent with this, and the description adds useful context about state transitions without contradicting any annotation.

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

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

The description is two concise sentences, front-loaded with the primary action, and includes an IMPORTANT warning that draws attention to the key side effect. Every sentence serves a purpose with no redundant or extraneous text.

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

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

For a simple state-change operation with four parameters and no output schema, the description covers the core behavior, the state change, and a usage prerequisite. It does not explain return values or error behaviors, but these are not critical for this tool type, and the annotations provide additional context (idempotency, non-destructiveness). Overall, it is 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?

Schema description coverage is 100%, so all parameters are already fully described in the schema. The description does not add parameter-specific details, but the baseline for high schema coverage is 3, and the description's mention of state (Closed) implicitly relates to the impact of parameters like close_code and close_notes without elaborating on them.

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

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

The description clearly states the tool's function: 'Close an incident by setting state to Closed (7).' This is a specific verb and resource, and it explicitly distinguishes itself from sibling tools like resolve_incident by naming the target state (Closed vs. Resolved). The warning about the incident typically being in Resolved state also differentiates it from other state-changing tools.

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

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

The description provides clear contextual guidance: 'The incident should typically be in Resolved state before closing, though this depends on instance configuration.' This implies the appropriate time to use the tool and a prerequisite. However, it does not explicitly name alternative tools or state when not to use it, so it doesn't fully meet the 'explicit when/when-not/alternatives' criterion.

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

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

Annotations mark it as read-only and open-world, and the description adds context about search groups, the default search group behavior, and how current_app affects search_all_scopes. It also notes the instance fallback to the SN_AUTH_ALIAS environment variable.

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

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

The description is well-structured with an opening summary, a paragraph on search groups, and a bulleted list of use cases. It is appropriately sized for a non-trivial tool, front-loaded with the primary action, and every sentence contributes value.

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

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

The description covers the search group mechanism, result contents (record name, table, field, line numbers), and related discovery tools. It omits explicit mention of pagination or error handling, but for a read-only search tool with rich annotations and schema, it is 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?

All seven parameters have schema descriptions, yielding a high schema coverage baseline of 3. The tool description adds conceptual context about search groups, helping to understand the search_group and table parameters, but it does not significantly extend parameter-specific details 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 searches for code across a ServiceNow instance, identifying scripts, business rules, script includes, and other artifacts. It uses a specific verb+resource structure and distinguishes itself from sibling tools like list_code_search_groups and query_table.

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 lists concrete use cases, such as finding scripts referencing a specific API, locating business rules, and verifying deployments. It also directs users to list_code_search_groups and list_code_search_tables for discovery, but it does not explicitly state when not to use this tool or name alternatives.

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

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

Beyond the annotations, the description discloses key behaviors: the copied flow lands in draft/unpublished state, gets a new sys_id, is independent of the source, returns the new sys_id, and prints the exact 'now-sdk transform' command. This adds substantial context that annotations alone do not provide, with no contradiction.

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

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

The description is well-structured: it opens with the core action, then explains the rationale, lifecycle, behavior, and a practical tip. Every sentence provides value—no filler or redundancy. Front-loaded with the essential 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 tool with no output schema, the description covers the return value (sys_id and command), the state of the copied flow, the requirement for a scope sys_id, and an alternative way to find it. It also embeds the tool within the broader lifecycle, making it fully self-contained.

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

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

The input schema already has 100% coverage with detailed descriptions for all four parameters. The tool description reinforces important nuances (e.g., target_scope must be a sys_id, source can be OOB) but does not add significantly 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 states a specific action ('Copy an existing ServiceNow Flow Designer flow') with a clear resource and target ('into a target scoped application'). It also distinguishes this tool from siblings by framing it as the best-practice first step for modifying flows, which is unique among the flow-related 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?

Explicitly says when to use: 'best-practice first step when you want to modify any flow', and explains why (OOB/shared flows should not be modified directly). Provides a lifecycle (copy_flow → pull → modify → push → test_flow → publish_flow) and directs users to list_scoped_apps for target_scope, giving clear usage context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds context about using the Stats API and server-side efficiency. It does not mention potential errors or rate limits, but the added performance context goes beyond the annotations.

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

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

The description is three sentences, each earning its place: what it does, how it works, and when to use it. Information is front-loaded and there is 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?

For a simple count tool with no output schema, the description sufficiently covers purpose, use cases, and performance. It does not explicitly describe the return value, but the name and purpose make it obvious. The example queries in the schema provide enough operational context.

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

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

Schema coverage is 100%, so the schema fully documents the three parameters (query, table, instance). The description only reiterates 'encoded query' and 'any ServiceNow table' without adding new semantic details beyond the schema.

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

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

The description uses a specific verb ('Count') with a clear resource ('records on any ServiceNow table') and explicitly mentions an optional filter ('encoded query'). It also distinguishes itself from retrieval tools by emphasizing efficient server-side counting via the Stats API.

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

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

It provides explicit use cases ('gauge data volumes') and contrasts with the alternative of querying all records client-side. However, it does not mention when to use sibling aggregation tools (e.g., aggregate_query) instead, so it lacks full exclusion guidance.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds that the article is created in 'draft' state by default and notes the HTML/wiki body options, plus an 'IMPORTANT' emphasis that it creates a new article on the instance. This adds useful behavioral context beyond the annotations.

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

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

The description is concise—about five sentences in three short paragraphs—and front-loads the core purpose. It avoids redundancy with the schema and provides the important publish hint 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 9-parameter creation tool with nested objects and no output schema, the description covers the essential creation behavior, default state, and body format choices. It does not describe the return value (e.g., sys_id of the created article), which would be helpful, but the rich schema compensates for this gap.

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

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

With 100% schema coverage, the schema already documents all parameters. The description adds practical value by noting that HTML is the more common body format, helping users choose between text and wiki fields, and by confirming the default workflow_state matches the schema default.

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 begins with 'Create a new knowledge article in a specified knowledge base,' which is a specific verb+resource statement. It also mentions the default 'draft' workflow state, distinguishing it from the sibling tool publish_kb_article.

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 directs users to publish_kb_article for making articles visible, providing a clear alternative. It also mentions that HTML is more common than wiki, aiding format choice, though it does not explicitly exclude update_kb_article for modifying existing articles.

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

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

Annotations already establish readOnlyHint=false, so the description's 'IMPORTANT: This creates a new category on the instance' adds minimal new information beyond emphasizing persistence. No contradiction.

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

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

The description is compact and front-loaded, with two short sentences plus an emphasis line. The IMPORTANT sentence is somewhat redundant, but it does not waste much space.

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 creation tool with full schema coverage, the description covers purpose and key parameters. It does not mention return value or error behavior, but no output schema exists and tool complexity is low.

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

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

Schema description coverage is 100%, so all parameters are already well-documented. The description repeats that label and knowledge_base_sys_id are required and parent_category is for subcategories, adding no new 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 uses a specific verb 'Create' with a clear resource 'category in a knowledge base'. It clearly distinguishes this from sibling tools like list_kb_categories or get_knowledge_base.

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

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

The description states required inputs (label, knowledge_base_sys_id) and optional parent_category, giving clear context for when to use. It doesn't explicitly name alternatives, but the create operation is unambiguous.

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

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

Annotations already indicate this is not read-only (readOnlyHint=false) and has open world side effects (openWorldHint=true). The description adds only 'This creates a new update set on the instance,' which is redundant with the tool's name. It does not disclose potential side effects, permissions required, or implications of 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 very short, but the 'IMPORTANT' sentence is somewhat redundant with the title and adds little value. It is not wasteful, but it could be more informative with the space used.

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 no output schema and minimal annotations, the description should explain prerequisites, potential side effects, or what happens on success. It lacks any contextual information beyond the action itself, making it incomplete for an agent to understand the full impact.

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 100% of parameters with detailed descriptions (name, instance, application, description). The tool description adds no additional parameter semantics 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 action: 'Create a new update set.' This is a specific verb+resource pair that distinguishes it from sibling tools like clone_update_set, list_update_sets, or set_current_update_set. The added 'IMPORTANT' clause reinforces that it operates on the instance.

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 versus alternatives. It does not mention scenarios where creating an update set is appropriate or when to prefer clone_update_set or set_current_update_set. The description provides no 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?

The description goes beyond the annotations by explicitly warning that multiple records (workflow, version, activities, transitions) are created, which aligns with the non-readOnly and openWorld annotations. It also discloses the orchestration sequence and the id/index referencing convention, providing behavioral context that is not present in the annotations.

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

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

The description is compact and front-loaded: the core purpose appears in the first sentence, followed by a concise bullet-like orchestration list and a short cautionary note. Every sentence adds value with no redundancy.

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

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

The description covers the main orchestration steps and important side effects, but it omits the return value (e.g., workflow sys_id), which is significant given there is no output schema. The note to 'review the specification carefully' is vague and doesn't highlight potential validation failures or required dependencies beyond 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?

With 100% schema description coverage, the baseline is 3. The description adds the crucial rule that activities in transitions are referenced by `id` field or array index, which is not fully captured in the individual schema descriptions for `transitions` and `start_activity`. This clarifies how to use multiple parameters together, raising the score to 4.

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

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

The description clearly identifies the tool's function: it creates a complete ServiceNow workflow from a single specification, enumerating the orchestration steps (workflow, version, activities, transitions, optional publish). This verb+resource phrasing distinguishes it from sibling tools like batch_create_records or execute_flow, which target different operations.

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

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

The opening sentence establishes a clear context: use this when you need to create a complete workflow from a specification rather than building its components individually. However, it does not explicitly state when not to use it or name alternative tools, so it lacks exclusionary guidance.

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

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

With annotations declaring readOnlyHint=true and openWorldHint=true, the description adds value by detailing what will be returned (table name, label, parent class, per-field attributes) and explaining that optional flags query additional data sources like sys_choice. It does not contradict the annotations and provides useful context about the read-only, exploratory nature of the operation.

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

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

The description is well-structured and concise. It opens with a clear summary sentence, follows with a compact return-value list, and then uses bullet points for key use cases. Every sentence provides useful information without redundancy or fluff.

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

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

The tool has six parameters and no output schema, but the description compensates by explaining the return structure and the effects of optional flags. It covers the main use cases and clearly indicates the optional data that can be included. However, it does not exhaustively describe all edge cases or behavior for invalid tables, which keeps it slightly below a perfect 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?

The input schema already provides comprehensive descriptions for all six parameters, including examples and defaults (e.g., 'include_choices: Include choice values for fields that have them'). The tool description restates some of this information (e.g., 'optionally choice values') but does not add significant new semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Discover the full schema of a ServiceNow table including all fields, types, references, and optionally choice values, relationships, UI policies, and business rules.' This is a specific verb-resource combination that distinguishes it from sibling tools like lookup_table or explain_field by focusing on comprehensive schema discovery.

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

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

The description provides explicit use cases: 'Understand the structure of a table before querying or scripting against it', 'Discover reference fields', 'Find choice values', and 'Review UI policies and business rules'. This gives clear context for when to use the tool, though it does not explicitly mention 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 declare destructiveHint=true and readOnlyHint=false, and the description adds useful behavioral context: foreground blocks, background returns immediately with a context ID, and quick skips execution details. It does not restate annotations and provides mode-specific behavior beyond what annotations offer.

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

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

The description is concise, with a clear one-sentence purpose followed by a focused paragraph on mode behavior. Every sentence adds value and no content is wasted.

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

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

The description covers the main execution modes, how to retrieve background results (naming follow-up tools), and when to use quick mode. It does not explain error handling or return formats, but the lack of an output schema shifts some burden to the description. Overall, it is sufficiently complete for a tool with 7 parameters and 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 input schema already provides full descriptions for all 7 parameters (100% coverage). The tool description does not add significant per-parameter detail, but it does contextualize the mode parameter within the foreground/background discussion. Baseline 3 is appropriate.

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

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

States a specific verb ('Execute') plus a specific resource type ('ServiceNow Flow Designer action by scoped name'). The phrase 'Actions are the lowest-level building blocks' clearly distinguishes it from sibling tools like execute_flow and execute_subflow.

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

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

Provides clear guidance on when to use foreground vs background modes and suggests background for flows with approval/wait steps. However, it does not explicitly name alternative tools for running full flows or subflows, so guidance on tool selection is implicit rather than explicit.

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

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

The description discloses critical behavior beyond what annotations provide: foreground mode blocks until completion, background mode returns a context ID for polling, and foreground mode will fail on flows with waiting states. It also warns that flows must be published. These are non-obvious operational constraints that significantly aid correct invocation.

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

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

The description is well-structured with a clear opening sentence, distinct paragraphs for mode behavior, and highlighted IMPORTANT/NOTE sections. Every sentence serves a purpose—purpose, mode semantics, and alternatives—without redundancy. It's appropriately sized for a complex 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?

Given the tool's complexity (7 parameters, dual execution modes, no output schema), the description covers all key operational aspects: how to run, polling mechanism, prerequisites, and alternative tools. It addresses the main pitfalls (wait states, unpublished flows) and sufficiently orients an agent for correct invocation.

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

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

The input schema already provides 100% parameter coverage with detailed descriptions (e.g., mode, quick, scope, inputs, timeout, instance, scoped_name). The tool description adds context about modes but does not materially enhance parameter meaning beyond what the schema already explains. Baseline 3 applies because the schema carries the burden.

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

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

The description clearly states the tool's function: "Execute a published ServiceNow Flow Designer flow by scoped name." It uses a specific verb ('execute'), identifies the resource, and provides implementation detail (sn_fd.FlowAPI). It distinguishes itself from siblings by referencing test_flow and get_flow_context_status, 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?

Explicit guidance is given for when to use this tool vs alternatives: flows with approval/wait steps MUST use background mode, and for unpublished flows, the description says to use test_flow instead. This directly addresses selection criteria and prevents misuse.

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 goes well beyond the annotations by explaining server-side execution with full GlideSystem API access, output via gs.print()/gs.info(), scope resolution nuances, and an explicit safety warning about executing code directly on the instance. These details add valuable behavioral context that annotations alone do not convey.

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

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

The description is structured in three focused paragraphs: an initial overview, a detailed scope behavior explanation, and a safety reminder. Each sentence serves a clear purpose, and the most critical information is front-loaded. There is no redundant text, making it highly efficient for its complexity.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers the target endpoint, available APIs, output capture methods, scope behavior, and safety precautions. The schema and annotations further fill in parameter and safety details, leaving no major 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?

The input schema provides 100% coverage with rich descriptions for all four parameters (script, scope, params, instance), including syntax, defaults, and usage examples. The description itself adds little to parameter semantics; the schema already handles this dimension thoroughly, so the baseline score of 3 is appropriate.

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

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

The description clearly specifies the verb 'Execute' and the resource 'JavaScript on a ServiceNow instance using Scripts - Background (the /sys.scripts.do endpoint)'. This distinguishes it from sibling tools like execute_subflow or execute_action, which target predefined workflows rather than arbitrary code.

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 offers implicit usage context by detailing scope behavior and warning to 'prefer read-only operations unless modification is explicitly intended,' but it does not explicitly state when to choose this tool over alternatives like execute_subflow or execute_flow. No direct comparisons or exclusions are provided, so guidance remains 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 declare destructiveHint=true and readOnly=false. The description adds valuable behavioral detail: foreground blocks until completion and returns outputs, background returns a context ID for polling, and quick mode skips execution detail records. It also clarifies that timeout only applies to foreground. This goes beyond annotations without contradicting them.

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

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

The description is four sentences, front-loaded with the core purpose and then expanding into mode behavior and input passing. Every sentence provides necessary context with no fluff. It's efficiently structured and easy to scan.

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

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

The tool has 7 parameters with no output schema, but the description explains the key behavioral concepts: foreground vs. background, timeout scoping, and quick mode. It also points to follow-up tools for polling and retrieval. Minor gaps exist (e.g., error handling), but there are dedicated sibling tools for that, and the description is sufficiently complete for a complex execution tool.

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

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

Schema coverage is 100%, so all parameters have descriptions. The description adds a general note on passing inputs as key-value pairs, but this is already reflected in the inputs parameter schema. While the description doesn't rehash every parameter, it doesn't need to; the schema does the heavy lifting, so a baseline 3 is appropriate.

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

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

The description clearly states 'Execute a ServiceNow Flow Designer subflow by scoped name' — a specific verb and resource. It differentiates from siblings by explicitly calling out subflows as 'reusable building blocks' and positions itself as 'the primary tool for testing subflows during development,' distinguishing it from execute_flow and execute_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?

The description provides clear usage context: foreground vs. background modes, with background explicitly recommended 'for flows with approval/wait steps.' It also references get_flow_context_status for polling, but it doesn't explicitly name alternatives like execute_flow or execute_action or state when not to use this tool. This is strong guidance but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful details about the output content (type, constraints, help text, choice values), but it does not disclose any additional behavioral traits such as failure modes, permission requirements, or whether fields without choices are omitted. With annotations present, this is adequate but not exceptional.

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: the first states the exact purpose and output contents, the second gives a clear usage directive. It is front-loaded, no filler, and every sentence earns its place.

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

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

For a read-only explanation tool with no output schema, the description covers the main intent, output expectations, and a usage cue. It does not mention error scenarios (e.g., field not found) or distinguish from similar field-related tools, but it is largely complete for its simplicity. A 4 is appropriate.

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% — every parameter (table, field, instance) has a meaningful description. The tool description itself does not add parameter-specific details beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get detailed explanation') and resource ('a specific field on a ServiceNow table'), and enumerates what the explanation includes (type, constraints, help text, choice values). This makes it clearly distinct from sibling table-level tools like 'discover_table_schema' or 'lookup_columns'.

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 usage context: 'Use this to understand what a field does... before reading or writing data.' This tells the agent when to use it, though it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the tool is known to be a safe read operation. The description adds valuable behavior context by naming the unload XML format and the endpoint, and noting the XML can be imported into another instance. 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 succinct and front-loaded with the core purpose, followed by a bulleted list of use cases. Every sentence earns its place with no filler.

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

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

For a read-only export tool with three fully documented parameters and no output schema, the description covers the key context: purpose, format, endpoint, and likely use cases. The XML output is implied by the phrase 'generate ServiceNow-native XML,' which is sufficient for this complexity level.

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

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

Schema description coverage is 100%, with all three parameters (table, sys_id, instance) fully described. The description does not add additional parameter-level detail beyond the schema, but it reinforces the single-record scope and the XML format, matching the baseline for well-documented schemas.

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

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

The description clearly states the tool's verb and resource: 'Export a single record from a ServiceNow instance in unload XML format.' It specifies the endpoint and distinguishes itself from the sibling import_records_xml by emphasizing the export direction and single-record scope.

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

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

The description provides four concrete common use cases (backup, transfer, comparing, update sets) that establish clear context for when to use the tool. It does not explicitly mention alternatives or when-not-to-use, 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 declare readOnlyHint and openWorldHint, and the description adds valuable context by stating the output (list of tests with sys_ids) and how it connects to run_atf_test. This goes beyond the annotations without contradicting them.

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

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

The description is compact and front-loaded: first sentence states the core action, second explains the return value, third gives usage guidance. Every sentence earns its place with no redundancy.

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

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

With no output schema, the description compensates by stating the return type and purpose. It covers the tool's role in the ATF workflow sufficiently for a search tool, though it could elaborate on output structure if 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 coverage is 100% with detailed descriptions for all five parameters. The description's mention of 'name, description, or category' only echoes the schema's search_term and category definitions, adding no new 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 it searches for ATF tests with specific fields (name, description, category) and returns sys_ids for later execution. It distinguishes itself from the sibling run_atf_test tool by explicitly noting the chaining workflow.

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 says 'Use this when you need to discover which ATF tests exist before running them,' providing clear usage context. It does not explicitly list exclusions or alternative tools, but the reference to passing sys_ids to run_atf_test implies the distinction from execution tools.

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

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

Annotations declare readOnlyHint and openWorldHint, which already signal a safe, read-only operation. The description adds meaningful behavioral context by stating that it 'returns the full record if found, or a clear message if not,' which goes beyond the hints. It does not conflict with annotations and enriches the agent's expectation of outcome.

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 only two sentences, front-loaded with the purpose and examples, then immediately followed by usage guidance. Every phrase earns its place, with no redundant content. It is compact and easily parsed.

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 lookup tool with no output schema, the description covers purpose, return behavior, examples, and usage context. It does not detail the exact record structure, but 'full record' is sufficient for most cases. The instance parameter is explained only in the schema, but that is acceptable given schema richness.

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

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

The schema provides 100% coverage with detailed descriptions for all three parameters (table, number, instance), so the description does not need to add much. It reinforces examples like 'INC0010001' that appear in the schema but adds no new meaning. Baseline 3 is appropriate since schema does the heavy lifting.

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 (find), resource (task record), and scope (by number), with concrete examples (INC0010001, CHG0030002). It distinguishes itself from generic lookup siblings like query_table and lookup_table by focusing on task records with a number, which aligns with task-related siblings like assign_task and resolve_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?

The description explicitly advises using this tool 'to look up sys_ids, check current state, or retrieve task details before performing actions like assigning or resolving.' This provides clear context for when to use it. However, it does not explicitly mention when not to use it or name alternatives (e.g., query_table for broader searches), so there are no exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds what the tool returns (version, install status, etc.) but does not disclose any behavioral nuances like error handling, auth requirements beyond the environment variable, or potential side effects. This adds some context but not deep behavioral 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 two sentences long, front-loaded with the main purpose, and includes a helpful usage tip without unnecessary filler. Every sentence earns its place.

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

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

For a read-only detail-fetching tool with good annotations and clear usage, the description is mostly complete. It lists the key return fields and provides the lookup_app flow. However, there is no output schema, so the description could benefit from a bit more detail on the shape or structure of the returned metadata, but it is not essential for 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%, and both parameters (app_id, instance) have descriptive text in the schema. The description does not add meaning beyond the schema; it only restates that the tool works by sys_id, which is already in the schema. Thus baseline 3 is appropriate.

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

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

The description clearly states the tool 'Get detailed information about a ServiceNow application by its sys_id' with a specific verb and resource. It also distinguishes itself from sibling tools like lookup_app by focusing on retrieving full details rather than resolving names.

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

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

The description provides explicit usage guidance: 'Use lookup_app to find an application's sys_id by name, then use this tool to get full details.' This tells when to use this tool and names the prerequisite alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows it's a safe read operation. The description adds the return fields (file name, content type, size, attached record), which is useful but not extensive. 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?

Two short, information-dense sentences. The main action is front-loaded, and every word earns its place with no filler or repetition.

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

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

For a simple retrieval tool, the description covers the essential elements: what it does, what identifier is needed, and what it returns. The instance param is self-explanatory in the schema, and the absence of an output schema is compensated by listing return fields.

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

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

Schema description coverage is 100%—both params have clear descriptions. The description's mention of 'sys_id' merely echoes the schema, adding no significant extra semantic value.

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

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

Description uses specific verb 'Get metadata' plus resource 'attachment' and identifier 'sys_id', making the purpose immediately clear. It distinguishes itself from sibling tools like list_attachments and upload_attachment by focusing on a single attachment's metadata.

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 the usage context: when you have a specific attachment's sys_id and need its metadata. It does not explicitly name alternative tools or exclusions, but the context is unambiguous, preventing confusion with listing or uploading 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 provide readOnlyHint=true and openWorldHint=true, so the safe read nature is conveyed. The description adds the item count detail but does not disclose additional behavioral traits like authentication requirements or return format, which are not covered by 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 that states the purpose and key detail without any filler. It is concise and well-structured.

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

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

This is a simple read-only tool with fully described parameters and no output schema. The description gives enough context (including the item count) to select and invoke the tool, though it could explicitly mention expected return fields.

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 fully described. The description only mentions sys_id and does not add meaning beyond the schema. Baseline of 3 is appropriate since the schema carries the parameter detail.

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

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

The description clearly states it 'gets details of a specific service catalog category by sys_id', which is a specific verb+resource+scope. It also mentions the item count, distinguishing it from sibling tools like list_catalog_categories 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 implies use when you need details of a specific category identified by sys_id, but it does not explicitly state when to use it over alternatives or provide exclusions. The guidance is implicit 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 declare readOnlyHint=true, which covers the safety profile. The description adds valuable behavioral context about the optional 'include_variables' parameter and its default behavior, explaining that it retrieves form fields. This goes 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 brief and front-loaded. The first sentence states the core purpose, and the second provides a useful usage hint. 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 read operation with no output schema, the description is adequate. It covers the main purpose, optional variables, and usage context. It doesn't discuss error cases or return formats, but those aren't critical for this tool's simplicity.

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

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

Schema description coverage is 100%, with each parameter already well-documented. The description reinforces the 'include_variables' default but adds no new meaning beyond what's in the schema. Baseline 3 is appropriate since the schema carries the semantic burden.

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

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

The description clearly states the tool's function: 'Get details of a specific service catalog item by sys_id, optionally including its variables.' This specific verb+resource combination distinguishes it from sibling tools like 'list_catalog_items' and 'list_catalog_item_variables'.

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

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

The description provides clear context for when to use the tool: 'Use this to understand what a catalog item offers and what information is needed before submitting a request.' While it doesn't explicitly exclude alternatives, this guidance is sufficient for an agent to decide when it's appropriate.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds meaningful context by explaining that it returns only direct relationships and accepts direction filters, which is not obvious from the annotations. It also clarifies that the sys_id can come from any CI class table. It does not disclose return format or pagination, but for a read-only tool with annotations covering safety, this is sufficient.

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

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

The description is two short paragraphs, with the first sentence stating the core purpose and the second giving use cases. The second paragraph adds practical parameter guidance. Every sentence 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 (5 parameters, 1 required) and strong schema coverage, the description is complete enough. It covers purpose, use cases, and parameter details, while annotations handle safety. Although there is no output schema, the description hints at return directions appropriately, making it sufficient for an agent to select and invoke the tool correctly.

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

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

The schema has 100% coverage for all 5 parameters, each with descriptions. The description adds value beyond the schema by providing concrete examples of relationship types (e.g., 'Depends on::Used by', 'Contains::Contained by') and clarifying that ci_sys_id can come from any CI class table. This enhances understanding without repeating schema details.

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

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

The description clearly states the verb and resource: 'Get direct relationships of a CMDB Configuration Item (CI).' It also specifies the return directions (upstream, downstream, or both) and distinguishes itself from the sibling tool 'traverse_cmdb_graph' by emphasizing 'direct' relationships. The use cases (impact analysis, dependency mapping, topology) further clarify intent.

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

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

The description provides clear context on when to use this tool: 'Use this for impact analysis, dependency mapping, and understanding CI topology.' However, it does not explicitly mention alternatives or when not to use it, such as comparing with 'traverse_cmdb_graph' for indirect relationships. The guidance is present but not fully exclusionary.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, and the description is consistent with these. The description adds no extra behavioral context such as return value format or potential errors, but for a simple read-only getter, the annotations sufficiently cover the safety profile.

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

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

The description is a single, front-loaded sentence that directly states the purpose with no redundant words. It is optimally concise and well-structured.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers the essential purpose. It does not explicitly describe the return value format, but the name and wording imply the current scope name. Given the low complexity and good annotations, the description is 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 fully documents the single 'instance' parameter with a detailed description, achieving 100% schema coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('Get') and resource ('currently active application scope'), making it distinct from related tools like set_current_scope or get_app_details. It is unambiguous and directly conveys the tool's function.

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

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

Usage context is implied: the tool is for when one needs to know the current application scope. However, the description does not explicitly mention when to prefer this over alternatives (e.g., set_current_scope) or any prerequisites, leaving the agent to infer the appropriate scenario.

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

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

The annotations already declare readOnlyHint: true, so the agent knows this is a safe read operation. The description adds the 'for the session' scoping detail, which is useful context beyond the annotations. However, it does not disclose what happens if no active update set exists, potential errors, or the exact return format, leaving some behavioral gaps.

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 containing exactly the necessary information—no wasted words. It is concise and well-structured, making it easy for an agent to parse quickly.

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

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

Given the tool's low complexity (one optional parameter, no output schema, read-only annotation), the description is mostly complete. It clearly states what is retrieved. However, it omits any detail about the return object's shape or possible error conditions, which would be useful for full completeness, especially since no output schema is provided.

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

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

The schema description coverage is 100% for the single 'instance' parameter, so the schema already fully documents its purpose. The description adds no parameter-related information, which is acceptable given the schema's completeness. The baseline score of 3 applies because the structured data does the heavy lifting.

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 ('Get') and resource ('currently active update set'), which distinguishes it from sibling tools like 'list_update_sets' (lists all) and 'set_current_update_set' (sets). The phrase 'for the session' adds scope, 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 indicates when to use the tool—when you need the active update set in the current session. However, it does not explicitly mention alternatives or exclusion criteria, such as 'use list_update_sets to see all sets' or 'use set_current_update_set to change it.' Despite this, the context is clear enough for an agent to infer appropriate usage.

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 valuable behavioral context beyond the annotations: it lists possible states (QUEUED, IN_PROGRESS, etc.) and describes the polling pattern. It doesn't detail error responses for invalid context IDs, but annotations already cover the read-only safety profile.

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

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

The description is concise and front-loaded with the core purpose. Every sentence contributes value: the initial query statement, the usage context, the state enumeration, and the typical workflow pattern. No redundant or filler content.

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

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

For a simple status-polling tool, the description is complete. It lists all possible states and suggests next steps (get_flow_outputs on COMPLETE, get_flow_error on ERROR). No output schema exists, but the description covers what the agent needs to know about the return value and workflow.

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

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

Schema description coverage is 100%, so both parameters (instance and context_id) are already fully described in the input schema. The description does not add additional parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: 'Query the current status of a flow execution by its context ID.' It specifies the resource (flow execution status) and the key input (context ID), distinguishing it from sibling tools like get_flow_outputs and get_flow_error.

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

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

Explicitly states when to use this tool: 'Use this to poll background flow executions started with execute_flow, execute_subflow, or execute_action in background mode.' It also provides a typical pattern with alternatives: 'once COMPLETE, call get_flow_outputs. If ERROR, call get_flow_error.'

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

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

With readOnlyHint=true annotation, the description correctly aligns as a read operation. It adds valuable behavioral context by explaining the precondition (only for failed flows) and that the return is the error message for diagnosing flow definition issues. No contradictions with annotations.

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

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

Two sentences, front-loaded with the core action and immediately useful usage condition. Every sentence adds value, no redundancy or fluff.

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

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

For a simple retrieval tool with 2 parameters and no output schema, the description fully covers purpose, usage trigger, parameter reference, and return value. It integrates well with sibling tools by referencing get_flow_context_status, and no critical information is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both instance and context_id fully documented in the schema. The description itself adds no additional parameter meaning beyond mentioning 'context ID' which mirrors the schema's required context_id field. Baseline 3 applies as schema does the heavy lifting.

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

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

The description clearly states the tool retrieves the error message from a failed flow execution by context ID, using specific verb 'retrieve' and naming the exact resource. It distinguishes itself from sibling tools like get_flow_logs and get_flow_outputs by focusing specifically on the error message.

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

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

The description gives an explicit when-to-use: 'Call this after get_flow_context_status shows ERROR'. However, it does not explicitly mention when not to use it or name alternative tools for related diagnostic needs, so it falls short of full alternative/exclusion guidance.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the bar is lower. The description adds valuable context: it specifies the underlying ProcessFlow API endpoint, states that flow operations logging is required, and explains that an unavailable report will include a notice. This goes beyond what annotations convey.

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

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

The description is well-structured: a concise purpose statement, followed by usage guidance, endpoint context, an important prerequisite, and a typical workflow. Every sentence adds value and the most important information is front-loaded.

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

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

Since there is no output schema, the description compensates by listing the types of information returned (per-action timing, inputs, outputs, metadata) and provides context about the endpoint and prerequisites. It does not detail error handling or the exact response structure beyond the notice, but it is complete enough for a diagnostic tool of this complexity.

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

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

The input schema has 100% coverage with descriptions for all four parameters. The tool description does not add extra parameter-specific semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Get' and specifies the resource 'rich execution details for a flow context' including per-action timing, inputs, outputs, and high-level metadata. It clearly distinguishes itself from sibling tools like get_flow_context_status and get_flow_logs by emphasizing detailed per-action diagnostics and positioning itself as the primary diagnostic tool.

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

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

It explicitly states when to use the tool: after test_flow or execute_flow, for diagnosing failures, inspecting inputs/outputs, and iterating on flow definitions. It also includes a typical workflow and a prerequisite (flow operations logging must be enabled). It does not explicitly mention when not to use it or name alternative tools, so it misses the top score.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral details: it explains that log entries include errors, debug output, and cancellation reasons, and that logs may be empty depending on execution success or reporting level. It also asserts that errors/warnings are always logged regardless of reporting level, which is important context not captured by annotations.

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

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

The description is concise and front-loaded: the first sentence states the core action, the second details content, and the third gives a critical caveat. Every sentence earns its place without repetition or fluff.

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

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

Although there is no output schema, the description clarifies what the tool returns (log entries with specific content) and when it may be empty. It also references the companion tool for a fuller picture. This is sufficient for a relatively simple read-only tool, with minor omissions like pagination behavior being covered by the limit parameter 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?

Schema description coverage is 100%, with each parameter already having a meaningful description (e.g., context_id identifies the flow execution, limit sets max entries, order_direction sorts). The description does not add extra parameter semantics, so it stays at the baseline for full schema coverage.

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

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

The description clearly states the tool's function: 'Retrieve flow execution log entries from sys_flow_log for a given context.' It specifies the source table and the input (context), and distinguishes itself from the sibling get_flow_execution_details by being the log retrieval counterpart.

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 recommends using this tool 'alongside get_flow_execution_details to get the full picture,' providing a clear alternative/complement. It also gives situational context by noting log entries may be empty for simple successes or when reporting level is NONE, and that errors/warnings are always logged.

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

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

With readOnlyHint=true, the description adds value by clarifying the return format (output name-value pairs) and the prerequisite status condition. It doesn't disclose failure behavior, but also doesn't contradict annotations.

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

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

Two tightly written sentences that front-load the core action and add a key precondition. No redundant phrases or filler.

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

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

For a simple read-only retrieval tool with full schema coverage, the description covers what it returns, the precondition, and the resource type. It is sufficient for an agent to know when and how to invoke it.

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

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

The input schema already provides full descriptions for both parameters (context_id and instance), achieving 100% coverage. The description repeats 'context ID' but adds no additional parameter-level detail 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 'Retrieve outputs from a completed flow/subflow/action execution by its context ID,' specifying the verb, resource, and key parameter. It distinguishes from sibling tools like get_flow_context_status (status) and get_flow_logs (logs) by focusing on the output values.

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 conditions usage on get_flow_context_status showing COMPLETE, providing a clear when-to-use rule. It doesn't name alternatives or exclusions, but the precondition is specific and actionable.

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

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

Annotations already declare readOnlyHint=true, and the description aligns with this by describing a read operation. It adds useful context by noting that the response includes the HTML body text, which goes beyond the structured annotations.

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

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

The description is two succinct sentences with action-first wording. Every sentence adds value, and there is no redundant or filler content.

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

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

The tool is simple, has no output schema, and the description communicates that full content including HTML body is returned. This is sufficient for the agent to understand the result, though the exact response structure is not specified.

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 detailed descriptions for both sys_id and instance. The description mentions 'by sys_id' but does not add significant meaning beyond what the schema already states.

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

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

The description clearly states the tool 'Get the full content of a knowledge article by sys_id, including the HTML body text.' This uses a specific verb and resource, and the focus on retrieving a single article by sys_id distinguishes it from siblings like list_kb_articles or create_kb_article.

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

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

The description provides explicit usage guidance: 'Use this when you need to read, review, or extract content from an article.' This gives clear context, though it does not explicitly mention alternative tools 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 declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context by specifying exactly what details are returned (article and category counts) and positioning it as a scoping tool before browsing. 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?

Two concise sentences that front-load the core function and include a usage guideline. No redundant information or filler.

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

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

For a simple get-by-id tool with read-only annotations, the description adequately explains purpose, return content, and usage context. The lack of an output schema is compensated by mentioning the included counts. It does not specify error behavior, but that is not critical for this tool's simplicity.

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

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

Schema description coverage is 100%, with both sys_id and instance well-documented. The description's mention of 'by sys_id' adds no additional semantic meaning beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the parameter details.

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

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

The description clearly states the tool gets details of a specific knowledge base by sys_id, including article and category counts. This distinguishes it from siblings like list_knowledge_bases (which lists all KBs) and get_kb_article (which gets article details).

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

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

The description provides a clear use case: 'Use this to understand the scope of a KB before browsing its contents.' It implies when to use this tool (as a precursor to browsing articles/categories) but does not explicitly mention alternatives or exclusions. However, the context is sufficient for a straightforward retrieval tool.

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

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

Annotations already declare the tool as mutative (readOnlyHint false) and destructive (destructiveHint true). The description reinforces this with 'mutative operation that creates or updates records' and adds a caution to verify content. It does not contradict annotations, but adds limited new behavioral context 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 concise and front-loaded, with the first sentence immediately stating the action and mechanism. The second sentence adds a clear warning and use cases. Every sentence earns its place with no redundancy or fluff.

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

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

Given the tool's moderate complexity (3 parameters, no output schema) and the presence of annotations, the description is largely complete. It covers purpose, usage, and safety, but could potentially mention error handling or what the response looks like. Overall, it is sufficient for an agent to select and invoke it correctly.

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

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

The input schema has 100% coverage, so the schema already fully describes each parameter. The description adds minimal new information about parameters, only referencing the XML format which is also mentioned in the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool imports XML records into a ServiceNow instance via the sys_upload.do processor, and specifies the format as ServiceNow unload XML. It distinguishes itself from sibling tools like export_record_xml by being the import counterpart, and from other creation tools by focusing on XML content.

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

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

The description explicitly states when to use this tool: 'for restoring configurations, migrating records between instances, or applying exported record definitions.' It also provides a clear caution about verifying XML content and target table. However, it does not explicitly mention alternatives or when not to use it, which is a minor gap.

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=true already convey a safe read operation. The description adds behavioral detail about output structure ('grouped by type'), which goes beyond the annotation. No contradictions or hidden side effects are mentioned; this is sufficient given the annotation coverage.

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 one tight sentence with no unnecessary words. It front-loads the action verb, specifies the resource, and adds illustrative examples in parentheses—all without bloat.

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

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

The description covers the tool's purpose, output format, and typical contents. While there is no output schema, the grouped-by-type description provides a mental model. It could mention limitations or dependencies, but for a read-only inspection tool, it is 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?

Schema description coverage is 100% for parameters sys_id and instance, so the baseline is 3. The description does not add parameter-specific semantics, but it implies the need for an update set identifier ('an update set's contents'). The schema already documents both parameters clearly.

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 specifies the verb 'inspect' and the resource 'update set's contents', and differentiates from sibling tools like list_update_sets by focusing on the components within an update set. The examples 'business rules, script includes' add specificity.

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

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

The description implies clear usage: when you need to see the components of a specific update set. It does not explicitly name alternatives or exclusions, but the context of 'inspect contents' is distinct enough to guide tool selection.

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

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

The description discloses that this is a MUTATIVE, LONG-RUNNING operation that blocks until completion or timeout, adding meaningful detail beyond the annotations (which only mark it destructive and non-idempotent). It also mentions the default timeout of 30 minutes, providing crucial operational 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 three sentences, front-loaded with the core action, and every sentence provides distinct value: action/resource, behavioral caveat, and usage context. No filler or redundancy.

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

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

Given the tool's mutative and long-running nature, the description covers expected behavior (blocking), timeout, and typical use case. However, there's no output schema, and the description doesn't explicitly state what the tool returns after completion (e.g., success status, installation logs), leaving a minor gap in expected outcomes.

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 detailed descriptions for every parameter, so the schema carries the heavy lifting. The description adds value by explaining the overall blocking/timeout behavior and referencing list_company_apps to find scope and sys_id, which indirectly clarifies the purpose of key parameters. However, it doesn't introduce new parameter-specific 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 uses a specific verb ('Install') and identifies a precise resource: applications from the company's ServiceNow application repository via the CI/CD API. It also distinguishes from sibling tools like install_store_app by specifying the company repository rather than the store, making the tool's scope 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?

It provides clear context for when to use the tool: 'Typically used for deploying custom applications across instances (e.g., dev -> test -> prod).' It also directs users to a related sibling tool (list_company_apps) for finding required parameters, which serves as an implicit prerequisite. It doesn't explicitly state when not to use it, but the guidance 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?

While annotations already indicate destructiveHint and readOnlyHint false, the description significantly expands on the behavioral profile: it explicitly labels the operation as 'MUTATIVE, LONG-RUNNING' and notes it 'blocks until installation completes or times out (default: 30 minutes).' It also discloses that installation adds tables, scripts, and configuration, and warns about capacity/entitlements—all beyond the annotation hints.

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

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

The description is well-structured with a clear opening sentence, an 'IMPORTANT' section, and a closing guidance line. It is somewhat longer than strictly necessary, but every sentence adds value—covering mutability, timeout, prerequisites, and discovery. The front-loading of key traits (mutative, long-running) is effective.

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 (mutative, long-running install operation) and absence of an output schema, the description is thorough. It explains what happens, how long it blocks, prerequisites (capacity, entitlements), and how to find installable apps. It does not explicitly describe the return value, but for a blocking operation with no output schema, the behavioral disclosure 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 coverage is 100% with detailed descriptions for all five parameters, so the baseline is 3. The description adds high-level context (e.g., 'Use get_app_details to see available versions') but does not materially increase per-parameter meaning beyond what the schema already provides. It does reinforce connection to discovery tools, but that is more usage guidance than 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: 'Install a ServiceNow store application on the target instance.' It specifies the resource (store application) and target (instance), and distinguishes from siblings like install_from_app_repo (different source) and update_store_app (update vs install).

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

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

The description gives explicit when-to-use guidance: 'Use search_store_apps with tab_context 'available_for_you' to find apps available for installation.' It also recommends reviewing app details with get_app_details and testing on sub-production, effectively guiding the agent through prerequisites and alternatives.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, and the description adds valuable behavioral context by stating it returns metadata for each attachment including file name, content type, and size. It does not contradict annotations. While it lacks details about limit behavior or empty results, the annotation coverage makes this a strong 4.

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

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

The description is two concise sentences, front-loaded with the core action and followed by a usage context sentence. There is no redundant or unnecessary phrasing.

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 4-parameter tool with 100% schema coverage and good annotations, the description plus schema provide sufficient information for invocation. It clarifies the purpose and return type. A slight gap is not mentioning behavior for records with no attachments or whether pagination is expected, but overall it is 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 four parameters (limit, table, instance, record_sys_id) having clear descriptions. The tool description adds no additional parameter semantics 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 uses a specific verb 'List' and resource 'file attachments on a ServiceNow record', and specifies the return type (metadata with file name, content type, size). This clearly distinguishes it from sibling tools like get_attachment_info or upload_attachment.

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

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

Provides explicit usage context: 'Use this to discover what files are attached to incidents, changes, catalog items, or any other record.' However, it does not mention when not to use it or point to alternatives, so it misses the 'when-not' element for a top score.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read nature is known. The description adds the sc_category table context and filter options, but it does not disclose the return format, pagination defaults, or any side effects beyond what annotations imply. This is reasonable but not rich behavioral detail.

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

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

The description is two sentences, front-loaded with the core action ('List service catalog categories'), and every word earns its place. It avoids fluff and presents the most important usage guidance succinctly.

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

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

For a read-only list tool with good annotations and a fully documented schema, the description is nearly complete. It conveys the resource, table, filters, and use case. It does not explicitly mention pagination or limits, but those are in the schema, so the description is adequate for tool selection and invocation.

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

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

Schema description coverage is 100%, with all 8 parameters individually described. The description reinforces which parameters are useful for filtering (parent category, catalog, active, title) but does not add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter burden.

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 lists service catalog categories from the sc_category table and mentions key filters. It distinguishes the list operation from related single-item tools like get_catalog_category through the plural 'categories' and the phrase 'browse the catalog's organizational structure,' though it does not explicitly name sibling alternatives.

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

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

The description provides clear context for when to use the tool ('Use this to browse the catalog's organizational structure') and lists likely filter criteria. However, it does not explicitly state when not to use it or mention alternatives such as get_catalog_category for retrieving a single category, so exclusions are absent.

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

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

Annotations already cover read-only and open-world behavior. The description adds the source table and filter capabilities, which is useful context beyond the annotations. It doesn't describe return format, but with annotations the bar is lower.

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

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

Two sentences, front-loaded with the main verb and resource. The first sentence covers functionality, the second covers usage 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 has 8 parameters but no output schema. The description adequately covers purpose and usage context, leaving parameter details to the schema. It could mention pagination or advanced query filtering, but given the schema and annotations, it is 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description paraphrases filter capabilities (text_search, category, catalog, active) but doesn't add new 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?

Description clearly states it lists service catalog items from the sc_cat_item table, and describes supported search and filtering. This distinguishes it from siblings like get_catalog_item and list_catalog_categories, which have different scopes.

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

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

Provides explicit guidance to use for browsing/searching before getting item details or submitting a request. This implies exclusions (not for details/requests) but does not name alternative tools explicitly. Strong context but could be more direct.

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 provide readOnlyHint and openWorldHint, so the description gains credit for adding the default inclusion of variable sets and the specific return fields. It also notes the ability to disable variable sets via a parameter. This goes beyond the annotations without contradicting them.

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

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

The description is appropriately sized with two short paragraphs. The first states the action and output, the second provides essential usage context and example variable types. Every sentence earns its place, and the key information is front-loaded.

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

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

For a list operation with no output schema, the description is complete: it details the return fields, explains when to use it (before submit_catalog_request), and describes the default behavior regarding variable sets. No critical information is missing for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema; it mentions variable set inclusion in prose but this is already covered in the include_variable_sets parameter description. The description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool lists variables (form fields) for a specific catalog item, enumerating the return fields (names, types, mandatory, defaults, help text). This distinguishes it from sibling tools like list_catalog_items or get_catalog_item which operate on catalog items themselves, not their variables.

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 this tool is 'Essential for understanding what data to provide when using submit_catalog_request', giving a clear when-to-use scenario. It does not mention when not to use it or name direct alternatives, but the context is strong enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe read operation. The description adds behavioral context by explaining what search groups are and that each instance typically has a default group. It does not contradict annotations and provides meaningful domain context beyond the structured fields.

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

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

The description is concise and well-structured: a clear first sentence stating purpose, followed by a short explanatory paragraph, and a final sentence with precise cross-tool usage. Every sentence earns its place with no redundancy or verbosity.

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

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

For a simple list tool with no output schema, the description provides sufficient context: what search groups are, default behavior, and how to use the results with related tools. It covers all necessary operational knowledge for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% for the two parameters (limit and instance), so the schema already fully documents them. The description does not add further parameter-level meaning beyond the schema, but it does contextualize the output fields (name, sys_id) in relation to other tools. Overall, it meets the baseline without adding extra 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 tool lists code search groups on a ServiceNow instance, using a specific verb and resource. It distinguishes itself from related sibling tools like code_search and add_code_search_table by explaining how its output is used as inputs to those tools.

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

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

The description provides explicit usage guidance: the group `name` should be used as the `search_group` parameter in `code_search`, and `sys_id` when adding tables via `add_code_search_table`. This clearly instructs when and how to use the tool's results, effectively differentiating it from alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds transparency by explaining what the returned tables represent: 'These are the tables and fields that are searched when performing a code search with that group.' This goes beyond the annotation by clarifying the output semantics. No contradictions with annotations.

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

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

The description is brief and well-structured: two paragraphs, each sentence adding value. The first sentence states the primary function, the second clarifies what the results mean, and the third/fourth provide usage guidance. No filler or repetition.

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

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

For a simple read-only list tool, the description is complete. It explains the output (tables and fields), provides use cases, and references sibling tools for related actions (`add_code_search_table` and `list_code_search_groups`). With annotations covering safety and schema fully documenting parameters, no additional context 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?

The input schema covers 100% of parameters with descriptions, including the note that `search_group` is the NAME (not sys_id) and to use `list_code_search_groups` for available groups. The description itself does not add additional parameter details beyond the schema, so the baseline score of 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'List the tables associated with a code search group.' It uses a specific verb ('List') and resource ('tables') and distinguishes itself from siblings by explaining these are the tables and fields searched during a code search. It also references related actions like `add_code_search_table`, further clarifying its role.

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

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

The description provides explicit use cases: 'Use this to understand what a search group covers, or to identify if a specific table is missing and needs to be added via add_code_search_table.' This tells the agent when to use the tool and introduces an alternative (`add_code_search_table`) for the case when a table is missing. It could more explicitly name non-use situations, but the guidance is clear.

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